@fitlab-ai/agent-infra 0.9.6 → 0.9.7

package/templates/.agents/skills/run-manual-validation/reference/discovery-and-execution.en.md

@@ -0,0 +1,67 @@
+# Automatic Discovery and Per-item Execution
+
+Read this file before parsing input, discovering manual-validation items, or constructing validation actions.
+
+## Input Modes
+
+| Input | Handling |
+|-------|----------|
+| Non-empty target and command surround a literal `--` | Explicit mode; the command is authoritative for that target |
+| A literal `--` is present but the target or command is empty | Invalid input; stop before `validation-run.started` |
+| No `--` and only a task ref | Automatic mode |
+| No `--` and additional positional arguments | Invalid or partial input; do not ignore arguments or guess a command |
+
+Explicit mode still reads available sources to map coverage, but it must not synthesize another command for the same target. Only automatic mode constructs actions for discovered items.
+
+## Work Gate Matrix
+
+| mode | source state | gate |
+|------|--------------|------|
+| `explicit` | `any` | `continue` |
+| `automatic` | `items` | `continue` |
+| `automatic` | `empty` | `stop` |
+| `automatic` | `unreadable-only` | `stop` |
+
+The user command is effective work in valid explicit mode. Empty or unreadable sources affect only coverage mapping and reporting and must not cause an early stop. Automatic mode depends on reliable discovery results.
+
+## Discovery Sources
+
+1. Read manual-validation items from the latest `review-code` returned by `task-artifact`; this is the canonical local source. Read only that round's structured list, never task.md prose, older reviews, the activity log, or comment history.
+2. Run `agent-infra-internal platform-pr inspect {task-id}` and read the bound PR body's pending manual-validation list from a successful response as the supplemental source.
+3. Deduplicate semantically by target, required environment, and expected assertion. Merge identical items with review-code details taking precedence, append PR-only items, and classify material conflicts as `unresolved`.
+4. Assign report-local IDs `MV-1..N` and record source, target, expected assertion, required capability, and candidate steps. Do not write the task ledger.
+
+## PR Source Status
+
+| PR inspect result | Local items exist | No local items |
+|-------------------|-------------------|----------------|
+| Success | Merge lists; use only local items if the PR list is empty | Use the PR list; stop before started when both lists are empty |
+| `no-op` + `PR_NOT_LINKED` | Use local items only | Stop normally before started |
+| `failed` or `blocked` | Continue with local items; record typed status, stable error code, and the source coverage gap | Fail closed before started and request a retry after platform access is restored |
+
+Explicit mode may run its authoritative command when PR inspection fails, but the report must state that the PR list could not be reconciled. Never treat a read failure as an empty list or record the raw remote response.
+
+## Classification and Safe Actions
+
+Assign exactly one classification per item:
+
+- `executable`: host capability is supported by sufficient evidence and the action is minimal, non-interactive, and scoped.
+- `unavailable`: the required platform, filesystem semantics, permission, container, or account is definitely absent.
+- `unknown`: only weak signals exist and a safe probe cannot prove capability.
+- `unsafe`: validation would require destructive, secret-exposing, or unsanitizable actions.
+- `unresolved`: sources materially conflict about the environment or expected assertion.
+
+Only `executable` items may run. Commands must not expose credentials, environment variables, full argv, absolute user paths, or raw transcripts. Leave a coverage gap when safety cannot be established.
+
+## Per-item Execution
+
+1. Invoke each executable item separately:
+
+   ```bash
+   ai task validate {task-ref} --scope snapshot --format json -- {command...}
+   ```
+
+2. Only when the item or first-run evidence proves a dependency on uncommitted content, original mounts, or in-place permissions, explicitly invoke that item a second time with `--scope inplace` and record the reason.
+3. One item failure does not stop independent remaining items. Record exit status, cleanup, and the sanitized JSON allowlist separately.
+4. When the list is non-empty but no item is `executable`, still create and complete a validation-run artifact after started; do not run placeholder or fabricated commands.
+5. Always stop before started for invalid input. In automatic mode, also stop before started without an artifact when both sources are reliably empty or the sole possible source is unreadable with no local items; those source-based stop conditions do not apply to valid explicit mode.

package/templates/.agents/skills/run-manual-validation/reference/discovery-and-execution.zh-CN.md

@@ -0,0 +1,67 @@
+# 自动发现与逐项执行
+
+在解析输入、发现人工校验项或构造验证动作前读取本文件。
+
+## 输入模式
+
+| 输入 | 处理 |
+|------|------|
+| literal `--` 前后分别有非空验证目标和命令 | 显式模式；命令为该目标的权威动作 |
+| 存在 literal `--`，但目标或命令为空 | 非法输入；在 `validation-run.started` 前停止 |
+| 不存在 `--`，且只有 task ref | 自动模式 |
+| 不存在 `--`，但还有位置参数 | 非法/半截输入；不得忽略参数或猜测命令 |
+
+显式模式也要读取可用来源以映射覆盖范围，但不得为同一目标另行合成命令。自动模式才为发现项构造动作。
+
+## 工作门禁矩阵
+
+| mode | source state | gate |
+|------|--------------|------|
+| `explicit` | `any` | `continue` |
+| `automatic` | `items` | `continue` |
+| `automatic` | `empty` | `stop` |
+| `automatic` | `unreadable-only` | `stop` |
+
+合法显式模式的用户命令本身就是有效工作；来源为空或不可读只影响覆盖映射和报告，不得触发早退。自动模式必须依赖可靠发现结果。
+
+## 发现来源
+
+1. 从 `task-artifact` 返回的最新 `review-code` 读取人工校验项，作为 canonical 本地来源。只读取该轮结构化的人工校验清单，不扫描 task.md 自由文本、旧审查轮次、活动日志或评论历史。
+2. 运行 `agent-infra-internal platform-pr inspect {task-id}`，从成功返回的绑定 PR 正文读取待人工验证清单，作为补充来源。
+3. 按目标、所需环境和预期断言语义去重。相同项合并来源并优先采用 review-code 细节；PR 独有项追加；关键要求冲突的项标为 `unresolved`。
+4. 为本轮清单分配局部 ID `MV-1..N`，记录来源、目标、预期断言、所需能力和候选步骤；不得写入 task ledger。
+
+## PR 来源状态
+
+| PR inspect 结果 | 本地有项目 | 本地无项目 |
+|-----------------|------------|------------|
+| 成功 | 合并清单；PR 空清单时仅用本地项 | 使用 PR 清单；两边均为空时 started 前正常停止 |
+| `no-op` + `PR_NOT_LINKED` | 仅使用本地项 | started 前正常停止 |
+| `failed` 或 `blocked` | 继续本地项；在报告记录 typed 状态、稳定错误码和来源覆盖缺口 | started 前 fail closed，提示恢复平台访问后重试 |
+
+显式模式在 PR 检查失败时仍可执行权威命令，但必须记录无法核对 PR 清单。不要把读取失败当作空清单，也不要记录原始远端响应。
+
+## 分类与安全动作
+
+逐项选择一种分类：
+
+- `executable`：宿主能力已有充分证据；动作最小、非交互且作用域受限。
+- `unavailable`：明确缺少所需平台、文件系统语义、权限、容器或账号。
+- `unknown`：仅有弱信号，安全探测也无法证明能力。
+- `unsafe`：只能通过破坏性、泄密或无法去敏的动作验证。
+- `unresolved`：来源对环境或预期断言存在关键冲突。
+
+只有 `executable` 可以运行。命令不得输出凭据、环境变量、完整 argv、绝对用户路径或原始 transcript；不能证明安全就保留覆盖缺口。
+
+## 逐项执行
+
+1. 每个可执行项分别调用：
+
+   ```bash
+   ai task validate {task-ref} --scope snapshot --format json -- {command...}
+   ```
+
+2. 仅当项目要求或首次证据证明依赖未提交内容、原挂载或原位权限时，再为该项显式调用一次 `--scope inplace`，并记录升级理由。
+3. 单项失败不阻止其余独立项；分别记录退出状态、cleanup 和去敏 JSON allowlist。
+4. 清单非空但没有 `executable` 项时，仍在 started 后生成 validation-run 产物并完成 lifecycle，不运行占位或伪造命令。
+5. 输入非法时始终在 started 前停止。自动模式下，两来源可靠地确认无项，或唯一可能来源不可读且本地无项时，也在 started 前停止且不写产物；合法显式模式不适用这两个来源停止条件。

package/templates/.agents/skills/run-manual-validation/reference/report-template.en.md

@@ -1,5 +1,11 @@
 # Validation Run Evidence
 
+## Input Mode
+
+- Mode: `{explicit|automatic}`
+- Input decision: {sanitized-input-decision}
+- PR source status: `{success|no-op|failed|blocked}` / `{stable-code-or-none}`
+
 ## State Check
 
 ```text
@@ -11,6 +17,12 @@ $ agent-infra-internal task-snapshot {task-id} --format text
 
 {target-and-coverage}
 
+## Discovered Items
+
+| ID | Source | Target | Required Capability | Expected Assertion | Classification |
+|----|--------|--------|---------------------|--------------------|----------------|
+| `MV-{N}` | `{review-code|pr|merged|explicit}` | {target} | {capability} | {expected-assertion} | `{executable|unavailable|unknown|unsafe|unresolved}` |
+
 ## Mode Decision
 
 - Mode: `{snapshot|inplace}`
@@ -28,6 +40,19 @@ $ agent-infra-internal task-snapshot {task-id} --format text
 {sanitized-ai-task-validate-json}
 ```
 
+## Per-item Results
+
+### MV-{N}
+
+- Source: `{source}`
+- Classification: `{classification}`
+- Scope: `{snapshot|inplace|not-run}`
+- Command name: `{basename-only|not-run}`
+- Exit status: `{exit-status|not-run}`
+- Runtime upgrade: {none-or-reason}
+- Result: {sanitized-result-or-coverage-gap}
+- Cleanup: {cleanup-result}
+
 ## Cleanup and Recovery
 
 {cleanup-and-recovery-result}

package/templates/.agents/skills/run-manual-validation/reference/report-template.zh-CN.md

@@ -1,5 +1,11 @@
 # 验证运行证据
 
+## 输入模式
+
+- 模式：`{explicit|automatic}`
+- 输入判定：{sanitized-input-decision}
+- PR 来源状态：`{success|no-op|failed|blocked}` / `{stable-code-or-none}`
+
 ## 状态核对
 
 ```text
@@ -11,6 +17,12 @@ $ agent-infra-internal task-snapshot {task-id} --format text
 
 {target-and-coverage}
 
+## 发现清单
+
+| ID | 来源 | 目标 | 所需能力 | 预期断言 | 分类 |
+|----|------|------|----------|----------|------|
+| `MV-{N}` | `{review-code|pr|merged|explicit}` | {target} | {capability} | {expected-assertion} | `{executable|unavailable|unknown|unsafe|unresolved}` |
+
 ## 模式判定
 
 - 模式：`{snapshot|inplace}`
@@ -28,6 +40,19 @@ $ agent-infra-internal task-snapshot {task-id} --format text
 {sanitized-ai-task-validate-json}
 ```
 
+## 逐项结果
+
+### MV-{N}
+
+- 来源：`{source}`
+- 分类：`{classification}`
+- Scope：`{snapshot|inplace|not-run}`
+- 命令名称：`{basename-only|not-run}`
+- 退出状态：`{exit-status|not-run}`
+- 运行时升级：{none-or-reason}
+- 结果：{sanitized-result-or-coverage-gap}
+- Cleanup：{cleanup-result}
+
 ## 清理与恢复
 
 {cleanup-and-recovery-result}

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

@@ -9,13 +9,15 @@ description: >
 
 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, 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. Codex also validates the CLI, features, hook trust/discovery, and App Server schema first; a failed preflight creates neither a receipt nor a workspace baseline. Claude Code's native start event still cannot provide stable actual model/effort evidence and returns `ORCHESTRATION_CLIENT_UNSUPPORTED`. 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. Codex prefers SubagentStart/Stop plus App Server actual evidence to activate, consume, and seal the unique receipt. When a custom role does not emit native start/stop, trusted parent PostTool spawn uniquely resolves the child from rollout evidence and a completed wait validates the terminal before idempotent sealing. Timed-out waits do nothing; only empty turns or protocol `inProgress` may wait, while malformed, identity/transport errors, or abnormal terminals pause. Other supported clients keep native start/stop correlation. After the child returns, run `advance` only for a sealed receipt. 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. 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.
+1. Resolve the canonical task ID, current Agent Client, and optional atomic policy flags, then run `task-snapshot`. If one explicit role field is present, all four are required.
+2. Before `begin-or-resume`, Codex selects a host. Without `AGENT_INFRA_CONTROL_TOKEN`, use direct-host. With task-bound control authority but no `AGENT_INFRA_CODEX_CONTROLLER_CONTEXT`, only run `codex-sandbox-controller run --task-id {task-id} --task-ref {task-ref}` with the complete policy and wait; the outer loop must not create a run, baseline, or receipt. With a context, run `verify-context --task-id {task-id}` first. Stop on any bootstrap, bundle, source/profile discovery, or context failure.
+3. Run `task-orchestration {task-id} begin-or-resume --client {client}` with the complete explicit policy. With no explicit policy, core reads that client's configured policy; existing v2/v3 runs use persisted policy. Stop on paused/completed results.
+4. Run `route`. On `completed`, run `agent-infra-internal task-verify {task-id} run-task.completed --format text` and stop. Only a `running` result with non-null `next` supplies action, role, round, artifact, requested model, and requested effort.
+5. Codex runs `codex-lifecycle capability-arm --task-id {task-id}` once. The current loop's real PostToolUse must attest that ordinary tool response. Pass only its marker token to `prepare --client {client} --capability-token {token}`. Before snapshotting, core atomically consumes it, verifies task, hook source, build, contract, and controller binding, and persists the capability session, turn, and tool-use origin. Activation then verifies that spawn belongs to the same session and turn and uses a distinct tool-use. Other clients use the same prepare without a token. Failure creates no baseline, receipt, or child.
+6. After prepare, run `task-orchestration <task-ref> dispatch` immediately before calling the fresh native child, then use route's exact model/effort and only the short task ref, skill, `--orchestrated`, and stage identity. The trusted hook-spawn first-observation time must fall between dispatch and the deadline. Its first provenance-sensitive command must be `await-activation --stage ... --round ... --artifact ... --role ...`; before `running`, it must not snapshot, emit stage-started, write business files, or start commit. Only explicit `recover-prepared` may clear an expired orphan when the task fingerprint is exact, no commit intent exists, and no matching unconsumed active lifecycle evidence remains.
+7. Codex uses SubagentStart/Stop and App Server actual evidence to activate, consume, and seal one v3 receipt; trusted parent fallback must produce the same provenance. Timed-out waits do nothing. Advance only a sealed receipt and repeat step 4 only while running.
+8. Create a fresh child each round and never follow up with an old reviewer. Each requested/actual mismatch needs its own host fallback reason. Capability, hook, source, controller, build, identity, ledger, or fingerprint failure pauses and fails closed.
+9. On pause or completion, run the matching typed verification and report the structured endpoint.
 
 ## Stop
 

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

@@ -9,13 +9,15 @@ description: >
 
 总控只编排，不直接执行任何阶段技能。执行前先读取 `.agents/rules/no-mid-flow-questions.md`、`.agents/rules/lifecycle-orchestration.md` 与 `reference/host-validation.md`。
 
-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}`；核心在记录工作区基线前校验两字段与宿主证据能力。Codex 还会先验证 CLI、feature、hook trust/discovery 与 App Server schema；任一 preflight 失败均不得创建 receipt 或工作区基线。当前 Claude Code 的原生 start 事件无法稳定提供 actual model/effort，因此仍返回 `ORCHESTRATION_CLIENT_UNSUPPORTED`。只有校验成功时才用当前客户端的 fresh 原生子 Agent 启动指定角色，并显式覆盖同一 model/effort；只传短任务引用、skill 名、字面执行标记 `--orchestrated` 和最小交接摘要，不传 receipt identity，不继承总控历史。子 Agent 必须把该标记转发给本阶段所有 provenance 敏感命令。
-5. Codex 优先用 SubagentStart/Stop 与 App Server actual evidence 激活、消费并封存唯一 receipt；当 custom role 未投递原生 start/stop 时，受信 parent PostTool spawn 从 rollout 唯一解析 child，completed wait 再验证 terminal 并幂等封存。timed-out wait 无动作；只有 empty turns 或协议 `inProgress` 可等待，malformed、身份/传输错误或异常 terminal 均暂停。其他受支持客户端沿用原生 start/stop hook 关联。子 Agent 返回后只对 sealed receipt 调用 `advance`；只有 `running` 才重复步骤 3，`paused` 或 `completed` 立即停止。
-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 告知用户。
+1. 解析规范任务 ID、当前 Agent Client，以及可选的原子策略 `--executor-model`、`--executor-reasoning-effort`、`--reviewer-model`、`--reviewer-reasoning-effort`，并执行 `agent-infra-internal task-snapshot {task-id} --format text`。任一显式策略字段出现时四个 role 字段必须完整，不得与配置拼接；两个角色可以使用同一模型。
+2. Codex 在 `begin-or-resume` 前选择宿主：没有 `AGENT_INFRA_CONTROL_TOKEN` 时使用 direct-host；有 task-bound control authority 但没有 `AGENT_INFRA_CODEX_CONTROLLER_CONTEXT` 时，只调用 `agent-infra-internal codex-sandbox-controller run --task-id {task-id} --task-ref {task-ref}`（转发完整显式策略）并等待其终态，外层不得创建 run、baseline 或 receipt；已有 context 时先调用 `verify-context --task-id {task-id}`。controller 的 bootstrap、bundle、source/profile discovery 或 context 任一校验失败即停止。
+3. 调用 `agent-infra-internal task-orchestration {task-id} begin-or-resume --client {client}` 并转发完整显式策略。完全没有显式策略时由核心读取当前 client 的 `agentClients[].orchestration`；已有 v2/v3 run 使用持久化策略。仅当核心返回 `ORCHESTRATION_MODEL_POLICY_REQUIRED` 时，先用 `agent-client model-selection` 展示 complete/partial/interactive-only 来源，再一次收集完整策略；未回答则不创建 run。若为 paused/completed，按结构化结果停止。
+4. 调用 `route` 并读取结构化结果。若返回 `completed`，立即运行 `agent-infra-internal task-verify {task-id} run-task.completed --format text` 并停止；仅当返回 `running` 且 `next` 非空时读取唯一 action、role、round、artifact、`requestedModel` 和 `requestedReasoningEffort`，不得自行推断。
+5. Codex 先调用一次 `agent-infra-internal codex-lifecycle capability-arm --task-id {task-id}`。该普通工具调用必须由当前 loop 的真实 PostToolUse 回写 attestation；仅把返回的 marker 中 token 传给 `prepare --client {client} --capability-token {token}`。核心在快照前原子消费 token，校验 task、hook source、build、contract 与 controller binding，并持久化 capability 的 session、turn、tool-use 来源。activation 再校验 spawn 与该来源属于同一 session/turn，且 spawn 使用独立的 tool-use。其他客户端直接调用同一 prepare（无 token）。任一失败不得创建 baseline、receipt 或 child。
+6. prepare 成功后，在调用 fresh 原生子 Agent 的紧邻前一步执行 `task-orchestration <task-ref> dispatch`，再显式覆盖 route 返回的 model/effort；只传短任务引用、skill 名、`--orchestrated` 与 stage/round/artifact/role。可信 hook-spawn 首次观察时间必须位于 dispatch 与 deadline 之间。child 的第一条 provenance-sensitive 命令必须是 `await-activation --stage ... --round ... --artifact ... --role ...`；返回 running 前禁止 snapshot、阶段 started、业务写入或 commit-start。超时由核心暂停；崩溃遗留 prepared receipt 只能在 exact workspace fingerprint、无 commit intent、无匹配的未消费 active lifecycle evidence 且 deadline 已过时显式 `recover-prepared`。
+7. Codex 用 SubagentStart/Stop 与 App Server actual evidence 激活、消费并封存唯一 receipt；受信 parent fallback 仍必须形成相同 v3 provenance。timed-out wait 无动作；只有 empty turns 或协议 `inProgress` 可等待，malformed、身份/传输错误或异常 terminal 均暂停。子 Agent 返回后只对 sealed receipt 调用 `advance`；只有 `running` 才重复步骤 4。
+8. 每轮创建新 child；禁止 follow-up 复用 reviewer。actual model/effort 与 requested 不同时必须有各自的宿主降级理由。任何 capability、hook、source、controller、build、身份、账本或 fingerprint 异常都调用 `pause` 并失败关闭。
+9. 完成或暂停后运行对应 typed verification，并把结构化 run 摘要、暂停原因、commit 终点或 clean completion evidence 告知用户。
 
 ## 停止
 

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

@@ -8,6 +8,7 @@ Before publishing support for a client, prove the lifecycle evidence chain with
 - Raw start/stop events, or the parent PostTool spawn/completed-wait fallback when custom roles omit them, stably correlate the 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`.
+- Direct-host project/managed source and sandbox isolated-user source preserve the same build, contract, profile, and controller provenance through prepare/start/stop/consume.
 
 ## Validation Sequence
 
@@ -16,5 +17,6 @@ Before publishing support for a client, prove the lifecycle evidence chain with
 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.
+6. For sandbox, run at least ten cold executor starts and ten cold reviewer starts. Record monotonic prepared, spawn-dispatch, SubagentStart, and activation-completed timestamps plus p50/p95/max. Enable only when max plus 20% fits the deadline and symlink/config/plugin/lease/context/build failure injection and terminal cleanup audits pass.
 
 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. Codex may advertise `experimental`, but every `prepare` must still pass static preflight and either native start/stop or the parent spawn/completed-wait fallback must produce verifiable consumed host evidence. The fallback may wait only for empty turns or protocol `inProgress`; malformed, identity/transport errors, or abnormal terminals pause deterministically.

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

@@ -8,6 +8,7 @@
 - 原始 start/stop 事件，或 custom role 缺少它们时的 parent PostTool spawn/completed-wait fallback，能稳定关联 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` 复核。
+- direct-host 的 project/managed source 与 sandbox controller 的 isolated-user source、build/contract/profile/controller digest 必须在 prepare/start/stop/consume 全链路一致。
 
 ## 验证顺序
 
@@ -16,5 +17,6 @@
 3. 分别验证 model/effort 的 requested/actual 一致路径、单项与双项有理由 fallback 路径，并确认缺 actual 字段会失败关闭。
 4. 对同一 commit 执行 candidate checkout 与 `npm pack` 安装验证，记录 tarball 哈希和结果。
 5. 仅把去敏摘要与非敏感 fixture 纳入版本库；token、绝对用户路径、transcript 内容和凭证必须删除或替换。
+6. sandbox backend 另做至少 10 次 executor 与 10 次 reviewer 冷启动，记录 prepared、spawn dispatch、SubagentStart、activation completed 的单调时钟及 p50/p95/max；仅当 max 加 20% 余量不超过 deadline，并通过 symlink/config/plugin/lease/context/build 失败注入和终态清理审计时启用。
 
 任一字段无法从真实宿主稳定观察时，该客户端的 orchestration capability 保持 `unsupported`，并把缺口记录为人工验证项。Codex 可声明为 `experimental`，但每次 `prepare` 仍必须通过静态 preflight，且原生 start/stop 或 parent spawn/completed-wait fallback 必须形成可验证的 consumed host evidence。fallback 只允许 empty turns/协议 `inProgress` 等待；malformed、身份/传输错误或异常 terminal 都稳定暂停。

package/templates/.agents/skills/update-agent-infra/scripts/sync-templates.js

@@ -82,7 +82,6 @@ const DEFAULTS = {
       ".agents/skills/",
       ".agents/templates/",
       ".agents/workflows/",
-      ".agents/workspace/README.md",
       ".git-hooks/check-large-files.cjs",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
@@ -110,7 +109,16 @@ const DEFAULTS = {
       ".git-hooks/pre-commit",
       ".gitignore"
     ],
-    "ejected": []
+    "ejected": [],
+    "retiredManaged": [
+      {
+        "path": ".agents/workspace/README.md",
+        "templateHashes": [
+          "sha256:967b27ca4008154c5abf99a1df728242f80ed3ace9bd98eb2828bc1c76af826c",
+          "sha256:15aa21942cf2a1396d27834f1d3d723b61a46f8d14600b706f39f3bebc21aea3"
+        ]
+      }
+    ]
   }
 };
 
@@ -1224,6 +1232,26 @@ function entryVariantRels(entry, allSet, platform) {
   return rels;
 }
 
+function ensureRuntimeWorkspace(projectRoot) {
+  const directories = [
+    path.join(projectRoot, '.agents'),
+    path.join(projectRoot, '.agents', 'workspace'),
+    ...['active', 'blocked', 'completed', 'archive'].map((state) =>
+      path.join(projectRoot, '.agents', 'workspace', state)
+    )
+  ];
+  for (const directory of directories) {
+    if (fs.existsSync(directory)) {
+      const stat = fs.lstatSync(directory);
+      if (!stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new Error(`Runtime workspace path must be a real directory: ${directory}`);
+      }
+      continue;
+    }
+    fs.mkdirSync(directory, { mode: 0o700 });
+  }
+}
+
 function syncTemplates(projectRoot, templateRootOverride) {
   const configDir = path.join(projectRoot, '.agents');
   const cfgPath = path.join(configDir, '.airc.json');
@@ -1234,6 +1262,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
 
   const originalConfigText = fs.readFileSync(cfgPath, 'utf8');
   const cfg = JSON.parse(originalConfigText);
+  ensureRuntimeWorkspace(projectRoot);
   const configPathRel = norm(path.relative(projectRoot, cfgPath));
   let templateRoot = templateRootOverride;
   if (!templateRoot) {
@@ -1271,6 +1300,16 @@ function syncTemplates(projectRoot, templateRootOverride) {
     merged: [...(cfg.files.merged || [])],
     ejected: [...(cfg.files.ejected || [])]
   };
+  const retiredManaged = new Map((DEFAULTS.files.retiredManaged || []).map((retired) => {
+    const descriptor = typeof retired === 'string' ? { path: retired } : retired;
+    return [norm(descriptor.path), new Set(
+      (descriptor.templateHashes || []).map(trustedBaseline).filter(Boolean)
+    )];
+  }));
+  const planningRegistry = {
+    ...currentRegistry,
+    managed: currentRegistry.managed.filter((entry) => !retiredManaged.has(norm(entry)))
+  };
   const sharedDefaults = {
     managed: (DEFAULTS.files.managed || []).filter(
       (entry) => !isPathOwnedByOtherPlatform(entry, platformType)
@@ -1280,7 +1319,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
     ),
     ejected: [...(DEFAULTS.files.ejected || [])]
   };
-  const assetPlan = planProjectRegistry(currentRegistry, sharedDefaults, enabledTUIs);
+  const assetPlan = planProjectRegistry(planningRegistry, sharedDefaults, enabledTUIs);
   const managed = [...assetPlan.registry.managed];
   const merged = [...assetPlan.registry.merged];
   const ejected = [...assetPlan.registry.ejected];
@@ -1295,6 +1334,7 @@ function syncTemplates(projectRoot, templateRootOverride) {
   for (const target of Object.keys(managedBaselines)) {
     if (
       !guardedManaged.has(norm(target))
+      && !retiredManaged.has(norm(target))
       && !allClientManaged.some((entry) => assetMatches(entry, target))
     ) {
       delete managedBaselines[target];
@@ -1369,6 +1409,38 @@ function syncTemplates(projectRoot, templateRootOverride) {
     )
   );
 
+  for (const [entry, historicalTemplateHashes] of retiredManaged) {
+    const target = path.join(projectRoot, entry);
+    const owned = currentRegistry.managed.some((candidate) => norm(candidate) === entry);
+    if (!fs.existsSync(target)) continue;
+    const stat = fs.lstatSync(target);
+    const baseline = trustedBaseline(managedBaselines[entry]);
+    const localHash = stat.isFile() && !stat.isSymbolicLink()
+      ? sha256(fs.readFileSync(target))
+      : null;
+    const safeToRemove = owned
+      && localHash !== null
+      && (localHash === baseline || historicalTemplateHashes.has(localHash));
+    if (safeToRemove) {
+      fs.unlinkSync(target);
+      report.managed.removed.push(entry);
+      if (Object.prototype.hasOwnProperty.call(managedBaselines, entry)) {
+        delete managedBaselines[entry];
+        baselinesChanged = true;
+      }
+    } else {
+      report.managed.protected.push({
+        target: entry,
+        reason: owned && localHash !== null && baseline !== null
+          ? 'user-modified'
+          : (owned && localHash === null ? 'invalid-type' : 'unknown-origin'),
+        baseline,
+        local: localHash,
+        template: null
+      });
+    }
+  }
+
   const templateSources = Array.isArray(cfg.templates?.sources) ? cfg.templates.sources : [];
   report.templateSources.configured = templateSources.length;
   const { mergedRels, sourceMap } = mergeTemplateSources(templateRoot, templateSources, report);

package/templates/.agents/workspace/README.en.md

@@ -1,26 +0,0 @@
-# AI Workspace
-
-This directory is the runtime workspace for multi-AI collaboration. All contents are **git-ignored** except for this README and `.gitkeep` files.
-
-## Directory Structure
-
-```
-.agents/workspace/
-  active/           # Currently active tasks and handoff documents
-  blocked/          # Tasks that are blocked and waiting for resolution
-  completed/        # Completed tasks (kept for reference)
-  logs/             # Collaboration logs and session records
-```
-
-## Usage
-
-- **active/**: Place task files here when work begins. Move them to `completed/` or `blocked/` as appropriate.
-- **blocked/**: Move tasks here when they cannot proceed. Document the blocker in the task file.
-- **completed/**: Move tasks here when they are done. These serve as a historical record.
-- **logs/**: Store session logs, AI conversation exports, or collaboration notes.
-
-## Important
-
-- Contents of this directory are **not version-controlled** (git-ignored).
-- Do not store anything here that needs to be shared via git.
-- Templates and workflow definitions belong in `.agents/`, not here.

package/templates/.agents/workspace/README.zh-CN.md

@@ -1,26 +0,0 @@
-# AI 工作区
-
-本目录是多 AI 协作的运行时工作区。除本 README 和 `.gitkeep` 文件外，所有内容均被 **git ignore**。
-
-## 目录结构
-
-```
-.agents/workspace/
-  active/           # 当前活跃的任务和交接文档
-  blocked/          # 被阻塞的任务，等待解决
-  completed/        # 已完成的任务（保留供参考）
-  logs/             # 协作日志和会话记录
-```
-
-## 使用方法
-
-- **active/**：工作开始时将任务文件放在这里。根据情况将其移至 `completed/` 或 `blocked/`。
-- **blocked/**：当任务无法继续时将其移至此处。在任务文件中记录阻塞原因。
-- **completed/**：任务完成后将其移至此处。这些作为历史记录保留。
-- **logs/**：存储会话日志、AI 对话导出或协作笔记。
-
-## 重要事项
-
-- 本目录的内容**不受版本控制**（已被 git ignore）。
-- 不要在这里存储需要通过 git 共享的内容。
-- 模板和工作流定义属于 `.agents/` 目录，而非此处。