@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -54,7 +54,7 @@
     "yaml": "^2.9.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/build.js && node scripts/build-inline.js",
+    "build": "node scripts/run-build.js",
     "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .git-hooks || true",
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",

package/templates/.agents/QUICKSTART.en.md

@@ -20,14 +20,14 @@ This makes Git invoke the hooks in the project repository's `.git-hooks/` direct
 
 ## Development Checkout CLI Alignment
 
-When developing agent-infra from a source checkout, install dependencies and rebuild the local CLI before running lifecycle orchestration:
+When developing the agent-infra CLI from a source checkout, install dependencies and rebuild it as needed:
 
 ```bash
 npm install
 npm run build
 ```
 
-Lifecycle hooks prefer the checkout's `dist/bin/internal-cli.js` when it exists and fall back to `agent-infra-internal` on `PATH` otherwise. Rebuild after CLI source changes. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
+Lifecycle hooks always invoke `agent-infra-internal` through `PATH`; they do not implicitly switch to checkout source or `dist`. In a Codex sandbox, the controller's `PATH`-first shim is authoritative and binds the controller's selected executable. Skills, rules, hooks, and task data continue to come from the current checkout. The commands above develop the CLI itself and do not change hook executable selection. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
 
 ```bash
 npm link

package/templates/.agents/QUICKSTART.zh-CN.md

@@ -20,14 +20,14 @@ git config core.hooksPath .git-hooks
 
 ## 开发检出中的 CLI 对齐
 
-从源码检出开发 agent-infra 时，请先安装依赖并重新构建本地 CLI，再运行生命周期编排：
+从源码检出开发 agent-infra CLI 时，请按需安装依赖并重新构建 CLI：
 
 ```bash
 npm install
 npm run build
 ```
 
-本地 `dist/bin/internal-cli.js` 存在时，生命周期 hook 会优先使用它；不存在时则回退到 `PATH` 上的 `agent-infra-internal`。修改 CLI 源码后需要重新构建。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
+生命周期 hook 始终通过 `PATH` 调用 `agent-infra-internal`，不会隐式切换到当前检出的 source 或 `dist`。在 Codex sandbox 中，controller 放在 `PATH` 首位的 shim 是权威入口，并绑定 controller 选定的 executable。skills、rules、hooks 和任务数据仍从当前检出读取。上面的命令只用于开发 CLI 本身，不会改变 hook 的 executable 选择。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
 
 ```bash
 npm link

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -1,13 +1,9 @@
 import { execFileSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
 import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const MAX_INPUT_BYTES = 64 * 1024;
-const repoPackageJson = fileURLToPath(new URL('../../package.json', import.meta.url));
-const sourceInternalCli = fileURLToPath(new URL('../../bin/internal-cli.ts', import.meta.url));
-const localInternalCli = fileURLToPath(new URL('../../dist/bin/internal-cli.js', import.meta.url));
 const codexHooks = fileURLToPath(new URL('../../.codex/hooks.json', import.meta.url));
 const clientIndex = process.argv.indexOf('--client');
 const client = clientIndex >= 0 ? process.argv[clientIndex + 1] : '';
@@ -17,22 +13,6 @@ if (client !== 'claude-code' && client !== 'codex') {
 }
 
 function internalCliInvocation(args) {
-  let isAgentInfraSourceCheckout = false;
-  try {
-    isAgentInfraSourceCheckout = JSON.parse(readFileSync(repoPackageJson, 'utf8')).name === '@fitlab-ai/agent-infra';
-  } catch {
-    // Installed project hooks do not require a repository package.json.
-  }
-  if (isAgentInfraSourceCheckout && existsSync(sourceInternalCli)) {
-    return {
-      command: process.execPath,
-      commandArgs: ['--experimental-strip-types', sourceInternalCli, ...args],
-      shell: false
-    };
-  }
-  if (existsSync(localInternalCli)) {
-    return { command: process.execPath, commandArgs: [localInternalCli, ...args], shell: false };
-  }
   return { command: 'agent-infra-internal', commandArgs: args, shell: process.platform === 'win32' };
 }
 
@@ -125,7 +105,7 @@ process.stdin.on('end', () => {
         input: JSON.stringify(normalized),
         shell,
         stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: 15_000
+        timeout: 30_000
       });
       process.stdout.write(output);
     } catch (error) {
@@ -147,11 +127,11 @@ process.stdin.on('end', () => {
     args.push(
       '--native-agent', String(nativeAgent),
       '--child-id', String(event.child_id || event.agent_id || event.thread_id || ''),
-      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || ''),
-      '--spawn-mode', String(event.spawn_mode || (client === 'claude-code' ? 'fresh' : ''))
+      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || '')
     );
+    if (event.spawn_mode) args.push('--spawn-mode', String(event.spawn_mode));
     if (event.model) args.push('--actual-model', String(event.model));
-    const actualEffort = event.actual_reasoning_effort || event.reasoning_effort || event.model_reasoning_effort;
+    const actualEffort = event.effort?.level || event.actual_reasoning_effort || event.reasoning_effort || event.model_reasoning_effort;
     if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
     if (event.model_fallback_reason) args.push('--model-fallback-reason', String(event.model_fallback_reason));
     if (event.reasoning_effort_fallback_reason) {
@@ -162,6 +142,11 @@ process.stdin.on('end', () => {
       '--native-agent', String(nativeAgent),
       '--child-id', String(event.child_id || event.agent_id || event.thread_id || '')
     );
+    if (client === 'claude-code') {
+      if (event.model) args.push('--actual-model', String(event.model));
+      const actualEffort = event.effort?.level || event.actual_reasoning_effort || event.reasoning_effort;
+      if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
+    }
   }
   try {
     const { command, commandArgs, shell } = internalCliInvocation(args);

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -5,12 +5,12 @@
 - The orchestrator only routes and delegates. Stage skills remain the single source of truth for behavior and artifacts.
 - Every stage and rework round uses a fresh executor. Every review uses a fresh reviewer; follow-up reuse is forbidden.
 - A reviewer may only write its review artifact and core-generated task metadata. Business-code, HEAD, or index changes invalidate the receipt.
-- An active run has one pending delegation. The child must pass the activation barrier before any stage side effect. Missing, late, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run.
+- An active run has one pending delegation. The child must pass the activation barrier before any stage side effect. Missing, late, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run (on the claude-code path, missing or mismatched model/effort evidence, and fork/spawn-mode evidence this host structurally does not provide, follow the recording rules in `.agents/skills/run-task/reference/host-validation.md` instead and are exempt from this; missing or mismatched `parentId`/`childId` still pauses).
 - The first release ends after one existing safely gated `commit`; it does not create a PR, monitor checks, or complete the task.
 
 ## Recovery
 
-`orchestration.json` is the detailed state source. A v3 run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Historical v2 state is read-compatible, but new Codex delegations require v3. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no commit intent or consumed authorization, and no matching unconsumed active lifecycle evidence. Unknown schemas and incomplete active v3 state fail closed.
+`orchestration.json` is the detailed state source. A current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
 
 ## Codex Host and Capability
 
@@ -22,8 +22,9 @@
 
 - A new run persists model and reasoning effort for both roles. Explicit policy is atomic across all four role fields; only a fully absent explicit policy may fall back to the current client's `agentClients[].orchestration`.
 - Route resolves requested model/effort by role, and prepare matches both before snapshotting. Native spawn must not inherit session defaults.
-- Native start records host-observed actual model/effort. Each mismatch needs its own fallback reason, and requested values must never be fabricated as actual evidence.
+- Native start records host-observed actual model/effort. Each mismatch needs its own fallback reason (the claude-code path may leave this blank and follow the recording rules instead), and requested values must never be fabricated as actual evidence.
 - Model selection is labeled as a complete catalog, partial catalog, or interactive-only guidance; a local override enum must not be presented as complete.
+- claude-code's requested reasoning effort does not yet support per-role dispatch (concurrent tasks would race on a shared file); `delegationEvidence.actualReasoningEffort` is declared `spawn-ack`, meaning it is only recorded when honestly observed in a native spawn lifecycle event (Start/Stop) — it is not a promise of per-role dispatch and does not gate activation.
 
 ## Stable Pause Conditions
 

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -5,12 +5,12 @@
 - 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
 - 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
 - reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
-- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停。
+- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停（claude-code 路径下 model/effort 证据的缺失或错配、以及该宿主结构上不提供的 fork/spawn-mode 证据，按 `.agents/skills/run-task/reference/host-validation.md` 的记录规则处理，不在此列；`parentId`/`childId` 的缺失或错配仍然暂停）。
 - 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
 
 ## 恢复语义
 
-`orchestration.json` 是详细状态源。v3 run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后升级；历史 v2 状态仅兼容读取，新的 Codex delegation 必须写 v3。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 commit intent/authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。迁移是 forward-only，未知 schema 或缺 provenance 的 active v3 一律失败关闭。
+`orchestration.json` 是详细状态源。current run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。读取时只接受当前 writer 的完整结构；未知字段、缺失字段、非法 provenance 或旧 run 一律失败关闭且不改写。升级 agent-infra 前必须完成或清空所有 active run。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。
 
 ## Codex 宿主与 capability
 
@@ -22,8 +22,9 @@
 
 - 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
 - route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
-- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason；requested 值不得补造 actual 证据。
+- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason（claude-code 路径下允许留空，按记录规则处理）；requested 值不得补造 actual 证据。
 - 模型选择能力必须标记 complete catalog、partial catalog 或 interactive-only guidance；局部 override 枚举不得冒充完整目录。
+- claude-code 的 requested reasoning effort 暂不支持按角色下发（跨任务共享文件存在写入竞态）；`delegationEvidence.actualReasoningEffort` 声明为 `spawn-ack`，语义为"仅能在宿主原生 spawn 生命周期事件（Start/Stop）里如实观察到时记录，不构成按角色下发的承诺，也不构成放行门禁"。
 
 ## 稳定暂停条件
 

package/templates/.agents/rules/task-management.en.md

@@ -28,7 +28,7 @@ Map user intent to the corresponding workflow command:
 - Historical `gemini` / `gemini-cli` remain read-only for `ai task log` rendering and are not writable
 - Manual-step exception: no matter which agent is used, a human-made decision is always declared as `human`
 
-The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`) hard-validate `--agent` against a whitelist: they accept a short token, a long name, or `human`, and reject non-standard values with the matching `*_PAYLOAD_INVALID` error; long names are normalized to the short token before being persisted or forwarded. The `ai task log` renderer keeps unknown tokens grouped as `human` but appends a visible `(unknown)` marker.
+The seven internal commands (`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`) hard-validate `--agent` against a whitelist: they accept a short token, a long name, or `human`, and reject non-standard values with the matching `*_PAYLOAD_INVALID` error; long names are normalized to the short token before being persisted or forwarded. The `ai task log` renderer keeps unknown tokens grouped as `human` but appends a visible `(unknown)` marker.
 
 ## State Snapshot and Completion Verification Entrypoints
 
@@ -68,7 +68,7 @@ The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` /
   `- {time} — **{base} [started]** by {agent} — started`
 - **done line** (written when the step completes, unchanged from today): the action is the base itself:
   `- {time} — **{base}** by {agent} — {completion summary}`
-- **Commit-specific attempt**: the commit skill must not hand-write started. `commit-start` writes a structured `Commit [started]` with `attempt`, `baseline`, and `agent` under the task lock; `commit-terminate` writes the matching `Commit [aborted]` when an attempt is abandoned before side effects. Aborted closes activity only and is never successful commit evidence.
+- **Commit execution boundary**: the commit skill must not hand-write task Activity Log, review anchors, receipts, or checkpoints. Task-bound direct and orchestrated modes both call the single `commit-operation.execute`; taskless direct is allowed only for `TASK_CONTEXT_NOT_FOUND` and creates no task-state side effects.
 - `{base}` is that skill's existing done action text, including `(Round {N})` (e.g. `Plan Task (Round 1)`). started and done must share the same `{base}` to pair.
 
 **Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.

package/templates/.agents/rules/task-management.zh-CN.md

@@ -28,7 +28,7 @@
 - 历史 `gemini` / `gemini-cli` 仅保留 `ai task log` 渲染兼容，不接受写入
 - 人工步骤例外：无论使用哪个 Agent，只要是人做的决定，统一声明 `human`
 
-六个内部命令（`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
+七个内部命令（`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
 
 ## 状态快照与完成验证入口
 
@@ -70,7 +70,7 @@
   `- {time} — **{基名} [started]** by {agent} — started`
 - **done 行**（步骤完成时写，与现状一致）：action 即基名本身：
   `- {time} — **{基名}** by {agent} — {完成说明}`
-- **Commit 专用 attempt**：commit 技能不得手写 started。`commit-start` 在任务锁内写入带 `attempt`、`baseline`、`agent` 的结构化 `Commit [started]`；无副作用放弃时由 `commit-terminate` 写匹配的 `Commit [aborted]`。aborted 只闭合活动日志，不构成提交成功证据。
+- **Commit 执行边界**：commit 技能不得手写 task Activity Log、review anchor、receipt 或 checkpoint。task-bound direct 与 orchestrated 都调用唯一 `commit-operation.execute`；taskless direct 只在 `TASK_CONTEXT_NOT_FOUND` 时允许，且不产生任务状态副作用。
 - `{基名}` 指该 SKILL 既有 done 条目的 action 文本，含 `(Round {N})`（如 `Plan Task (Round 1)`）。
   started 与 done 共用同一 `{基名}` 才能配对。
 

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

@@ -99,7 +99,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to blocked/, so read it from `.agents/workspace/blocked/{task-id}/task.md`). This block is independent of "Next step" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Archived to" and before "To unblock" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. Blocked task-bound sandboxes are protected from automatic batch cleanup; if cleanup is necessary, manually verify their identity first. This block is independent of "Next step" semantics.
 
 Output format:
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}`.
@@ -112,9 +112,7 @@ Required to unblock: {what's needed}
 Archived to: .agents/workspace/blocked/{task-id}/
 
 Optional: clean up this task's sandbox
-(The task is blocked and moved to blocked/; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
-
-ai sandbox rm {branch}
+(The task is blocked and moved to blocked/; task-bound sandboxes are protected from automatic `ai sandbox rm --unbound` cleanup. If cleanup is necessary, manually verify the container, control manifest, and worktree identity first.)
 
 To unblock when the issue is resolved:
   agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{activation note}"

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

@@ -100,7 +100,7 @@ agent-infra-internal task-verify {task-id} block-task.completed --format text
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 blocked/，从 `.agents/workspace/blocked/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。blocked task-bound 沙箱受保护，不通过自动批量清理；如确需清理，请人工核对身份。该块独立于「下一步」语义。
 
 输出格式：
 使用 `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
@@ -113,9 +113,7 @@ agent-infra-internal task-verify {task-id} block-task.completed --format text
 归档路径：.agents/workspace/blocked/{task-id}/
 
 可选：清理本任务的沙箱
-（任务已阻塞并移到 blocked/，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
-
-ai sandbox rm {branch}
+（任务已阻塞并移到 blocked/，task-bound 沙箱受保护，不会被 `ai sandbox rm --unbound` 自动删除；如确需清理，请先人工核对容器、控制清单和工作树身份。）
 
 解除阻塞时执行：
   agent-infra-internal task-lifecycle {task-id} activate --agent {standard-agent-token} --note "{恢复说明}"

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

@@ -106,7 +106,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the task.md you already loaded (the task has moved to completed/, so read it from `.agents/workspace/completed/{task-id}/task.md`). This block is independent of "Next steps" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after "Target path" and before "Next step" in the output below — only when BOTH (1) `.agents/.airc.json` has a `sandbox` field and (2) task.md's `branch` field exists and is not `main` / `master`; otherwise omit the whole block. Use the full `{task-id}` for cleanup; do not substitute the branch name. This block is independent of "Next steps" semantics.
 
 Output format:
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}`.
@@ -119,9 +119,9 @@ Status label: {status-label or skipped}
 Target path: .agents/workspace/completed/{task-id}/
 
 Optional: clean up this task's sandbox
-(The task is archived; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+(The task is completed and archived; the sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
 
-ai sandbox rm {branch}
+ai sandbox rm {task-id}
 
 Next step - inspect the moved task:
 {next-step-commands}

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

@@ -105,7 +105,7 @@ agent-infra-internal task-verify {task-id} cancel-task.completed --format text
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 completed/，从 `.agents/workspace/completed/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。清理时使用完整 `{task-id}`，不要改用 branch 名。该块独立于「下一步」语义。
 
 输出格式：
 使用 `agent-infra-internal agent-client next-steps --skill check-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
@@ -118,9 +118,9 @@ agent-infra-internal task-verify {task-id} cancel-task.completed --format text
 目标路径：.agents/workspace/completed/{task-id}/
 
 可选：清理本任务的沙箱
-（任务已归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+（任务已完成并归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
 
-ai sandbox rm {branch}
+ai sandbox rm {task-id}
 
 下一步 - 查看已转移任务：
 {next-step-commands}

package/templates/.agents/skills/close-codescan/SKILL.en.md

@@ -93,7 +93,7 @@ Only `status=applied|no-op` means local archival completed. If the API dismissal
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the cleanup hint only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, (3) that task's task.md `branch` exists and is not `main` / `master`, and (4) task state and sandbox workspace identity were cross-validated without conflict. The state and identity select the command: use the full `{task-id}` only for `completed` + `task-bound`; use `{branch}` only when `branch-only` identity was explicitly verified; omit an automatic cleanup command for `active`; for `blocked` / `archive`, render a manual-verification note without a command. If state or identity is missing or conflicting, omit the whole block. Dismissing the alert never implies that the task is completed. This block is independent of "Next step" semantics.
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
 
@@ -110,7 +110,11 @@ View: {html_url}
 Note: it can be reopened on the platform if necessary.
 
 Optional: clean up this task's sandbox
-(The related task's sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+(Only for a `completed` related task with `task-bound` identity, use the full task ID:)
+
+ai sandbox rm {task-id}
+
+(Only when `branch-only` identity was explicitly verified, use the branch name:)
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/close-codescan/SKILL.zh-CN.md

@@ -93,7 +93,7 @@ agent-infra-internal task-lifecycle {task-id} close-codescan --agent {standard-a
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该任务 task.md 的 `branch` 存在且不是 `main` / `master`、(4) 任务状态与沙箱 workspace identity 已交叉校验且无冲突时，才渲染清理提示。状态和 identity 决定命令：仅 `completed` + `task-bound` 使用完整 `{task-id}`；仅在明确核对为 `branch-only` 时使用 `{branch}`；`active` 不渲染自动清理命令；`blocked` / `archive` 只渲染人工核对提示，不渲染命令。状态或 identity 缺失、冲突时整段省略；关闭告警本身不能推断任务已完成。该块独立于「下一步」语义。
 
 使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 
@@ -110,7 +110,11 @@ Code Scanning 告警 #{alert-number} 已关闭。
 注意：如有需要，可在 平台上重新打开。
 
 可选：清理本任务的沙箱
-（关联任务的沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+（仅在关联任务为 `completed` 且 identity 为 `task-bound` 时，使用完整任务 ID：）
+
+ai sandbox rm {task-id}
+
+（仅在明确核对 identity 为 `branch-only` 时，使用分支名：）
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/close-dependabot/SKILL.en.md

@@ -101,7 +101,7 @@ Only `status=applied|no-op` means local archival completed. If the API dismissal
 
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
-> **Optional sandbox-cleanup hint (gated)**: Render the "Optional: clean up this task's sandbox" block — placed after the "Note:" line and before "Next step" in the output below — only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, and (3) that related task's task.md `branch` field exists and is not `main` / `master`; otherwise omit the whole block. `{branch}` is the `branch` value from the related task.md located in step 7. This block is independent of "Next step" semantics.
+> **Optional sandbox-cleanup hint (gated)**: Render the cleanup hint only when ALL of (1) `.agents/.airc.json` has a `sandbox` field, (2) step 7 located a related task by the alert number, (3) that task's task.md `branch` exists and is not `main` / `master`, and (4) task state and sandbox workspace identity were cross-validated without conflict. The state and identity select the command: use the full `{task-id}` only for `completed` + `task-bound`; use `{branch}` only when `branch-only` identity was explicitly verified; omit an automatic cleanup command for `active`; for `blocked` / `archive`, render a manual-verification note without a command. If state or identity is missing or conflicting, omit the whole block. Dismissing the alert never implies that the task is completed. This block is independent of "Next step" semantics.
 
 Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}`.
 
@@ -118,7 +118,11 @@ View: {alert-url}
 Note: it can be reopened on the platform if necessary.
 
 Optional: clean up this task's sandbox
-(The related task's sandbox container and per-branch config directory are not reclaimed automatically. Run this if you no longer need them:)
+(Only for a `completed` related task with `task-bound` identity, use the full task ID:)
+
+ai sandbox rm {task-id}
+
+(Only when `branch-only` identity was explicitly verified, use the branch name:)
 
 ai sandbox rm {branch}
 

package/templates/.agents/skills/close-dependabot/SKILL.zh-CN.md

@@ -101,7 +101,7 @@ agent-infra-internal task-lifecycle {task-id} close-dependabot --agent {standard
 
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
-> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该关联任务 task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「注意：…」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取第 7 步定位到的关联任务 task.md 的 `branch` 值。该块独立于「下一步」语义。
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) 第 7 步按告警号定位到了关联任务、(3) 该任务 task.md 的 `branch` 存在且不是 `main` / `master`、(4) 任务状态与沙箱 workspace identity 已交叉校验且无冲突时，才渲染清理提示。状态和 identity 决定命令：仅 `completed` + `task-bound` 使用完整 `{task-id}`；仅在明确核对为 `branch-only` 时使用 `{branch}`；`active` 不渲染自动清理命令；`blocked` / `archive` 只渲染人工核对提示，不渲染命令。状态或 identity 缺失、冲突时整段省略；关闭告警本身不能推断任务已完成。该块独立于「下一步」语义。
 
 使用 `agent-infra-internal agent-client next-steps --skill complete-task --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
 
@@ -118,7 +118,11 @@ agent-infra-internal task-lifecycle {task-id} close-dependabot --agent {standard
 注意：如有需要，可在平台侧重新打开。
 
 可选：清理本任务的沙箱
-（关联任务的沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+（仅在关联任务为 `completed` 且 identity 为 `task-bound` 时，使用完整任务 ID：）
+
+ai sandbox rm {task-id}
+
+（仅在明确核对 identity 为 `branch-only` 时，使用分支名：）
 
 ai sandbox rm {branch}