@fitlab-ai/agent-infra 0.7.2 → 0.7.3

package/lib/sandbox/commands/start.ts

@@ -0,0 +1,61 @@
+import { loadConfig } from '../config.ts';
+import {
+  assertValidBranchName,
+  containerNameCandidates,
+  sandboxBranchLabel,
+  sandboxLabel
+} from '../constants.ts';
+import { detectEngine } from '../engine.ts';
+import {
+  fetchSandboxRows,
+  resolveBranchArg,
+  selectSandboxContainer,
+  startSandboxContainer
+} from './list-running.ts';
+
+const USAGE = `Usage: ai sandbox start <branch | TASK-id | N | '#N'>
+
+Start an existing sandbox container that has stopped (for example after the
+Docker daemon was restarted or replaced). The container must already exist:
+if none is found, run 'ai sandbox create <branch>' first. A container that is
+already running is left untouched.`;
+
+export async function start(args: string[]): Promise<void> {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(`${USAGE}\n`);
+    if (args.length === 0) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  const [firstArg = ''] = args;
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const branch = resolveBranchArg(firstArg, { repoRoot: config.repoRoot });
+  assertValidBranchName(branch);
+
+  const { running, nonRunning } = fetchSandboxRows(
+    engine,
+    sandboxLabel(config),
+    sandboxBranchLabel(config)
+  );
+  const found = selectSandboxContainer(
+    [...running, ...nonRunning],
+    containerNameCandidates(config, branch)
+  );
+
+  if (!found) {
+    throw new Error(
+      `No sandbox container for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`
+    );
+  }
+
+  if (found.running) {
+    process.stdout.write(`Sandbox '${found.name}' is already running.\n`);
+    return;
+  }
+
+  startSandboxContainer(engine, found.name);
+  process.stdout.write(`Started sandbox '${found.name}'.\n`);
+}

package/lib/sandbox/index.ts

@@ -6,6 +6,9 @@ Commands:
                                Enter sandbox or run a command. N (bare) is the
                                recommended form for task short ids (e.g.
                                'ai sandbox exec 11'); '#N' is also accepted.
+  start <branch | TASK-id | N | '#N'>
+                               Start an existing stopped sandbox container
+                               (e.g. after the Docker daemon restarted)
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
@@ -54,6 +57,11 @@ export async function runSandbox(args: string[]): Promise<void> {
       }
       break;
     }
+    case 'start': {
+      const { start } = await import('./commands/start.ts');
+      await start(rest);
+      break;
+    }
     case 'ls': {
       const { ls } = await import('./commands/ls.ts');
       ls(rest);

package/lib/table.ts

@@ -1,7 +1,11 @@
+import pc from 'picocolors';
+
 function formatTable(
   headers: readonly string[],
-  rows: readonly (readonly string[])[]
+  rows: readonly (readonly string[])[],
+  options: { zebra?: boolean } = {}
 ): string[] {
+  const { zebra = false } = options;
   const columnCount = headers.length;
   const widths = headers.map((header, i) => {
     const headerLen = header.length;
@@ -26,7 +30,15 @@ function formatTable(
     return parts.join('  ').trimEnd();
   };
 
-  return [renderRow(headers), ...rows.map((row) => renderRow(row))];
+  const dataLines = rows.map((row, i) => {
+    const line = renderRow(row);
+    // Zebra stripes: dim even-numbered data rows (rows 2, 4, 6... -> 0-based
+    // odd index). The header and odd rows are left untouched. When zebra is
+    // off, pc.dim is never called, so the output is byte-identical to before.
+    return zebra && i % 2 === 1 ? pc.dim(line) : line;
+  });
+
+  return [renderRow(headers), ...dataLines];
 }
 
 export { formatTable };

package/lib/task/commands/ls.ts

@@ -129,7 +129,7 @@ function ls(args: string[] = []): void {
     r.branch,
     r.title
   ]);
-  for (const line of formatTable(TABLE_HEADERS, tableRows)) {
+  for (const line of formatTable(TABLE_HEADERS, tableRows, { zebra: Boolean(process.stdout.isTTY) })) {
     process.stdout.write(`${line}\n`);
   }
   process.stdout.write(`Total: ${rows.length} tasks\n`);

package/lib/task/short-id.ts

@@ -70,6 +70,16 @@ function loadShortIdByTaskId(repoRoot: string): Map<string, string> {
   return map;
 }
 
+/**
+ * Resolve a branch to its active-task short id (`#NN`), or `null` when no
+ * active task is bound to that branch.
+ *
+ * Two-state semantics: this only consults the active registry
+ * (`active/.short-ids.json`) plus each `active/{taskId}/task.md`. Tasks moved
+ * to completed/blocked/cancelled/archive have already released their short id,
+ * so their branches return `null` — in `ai sandbox ls` that surfaces as `-`,
+ * meaning the sandbox is free to remove.
+ */
 function lookupShortIdByBranch(
   branch: string,
   repoRoot: string,

package/lib/update.ts

@@ -17,7 +17,8 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
-  requiresPullRequest?: boolean;
+  requiresPullRequest?: boolean;       // legacy field; read-only, migrated to prFlow then removed
+  prFlow?: 'required' | 'disabled';
   sandbox?: Record<string, unknown>;
   task?: { shortIdLength: number };
   labels?: Record<string, unknown>;
@@ -27,7 +28,6 @@ type UpdateConfig = {
 
 type Defaults = {
   platform: { type: string };
-  requiresPullRequest: boolean;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
   labels: Record<string, unknown>;
@@ -41,6 +41,25 @@ const defaults = JSON.parse(
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
 
+// One-time migration of the legacy project-level PR switch to the three-state
+// `prFlow` preference. `true` (the old default / "PR flow on") maps to the
+// strong constraint `required`; `false` maps to `disabled`. A missing or
+// already-migrated config is left untouched (idempotent). Returns the new
+// prFlow value when a migration happened, otherwise null.
+function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
+  if (config.requiresPullRequest === true) {
+    delete config.requiresPullRequest;
+    config.prFlow = 'required';
+    return 'required';
+  }
+  if (config.requiresPullRequest === false) {
+    delete config.requiresPullRequest;
+    config.prFlow = 'disabled';
+    return 'disabled';
+  }
+  return null;
+}
+
 function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
   const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
   if (!top.startsWith('.')) return false;
@@ -195,7 +214,7 @@ async function cmdUpdate(): Promise<void> {
   const sandboxAdded = !config.sandbox;
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
-  const requiresPullRequestAdded = config.requiresPullRequest === undefined;
+  const prFlowMigrated = migratePrFlow(config);
   let configChanged = changed;
 
   if (platformAdded) {
@@ -218,8 +237,7 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
-  if (requiresPullRequestAdded) {
-    config.requiresPullRequest = defaults.requiresPullRequest;
+  if (prFlowMigrated) {
     configChanged = true;
   }
 
@@ -233,7 +251,7 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || requiresPullRequestAdded) {
+    } else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || prFlowMigrated) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
@@ -246,8 +264,8 @@ async function cmdUpdate(): Promise<void> {
       if (labelsAdded) {
         info(`Default labels.in config added to ${CONFIG_PATH}.`);
       }
-      if (requiresPullRequestAdded) {
-        info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+      if (prFlowMigrated) {
+        info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
       }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
@@ -264,8 +282,8 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && platformAdded) {
       info(`Default platform config added to ${CONFIG_PATH}.`);
     }
-    if (hasNewEntries && requiresPullRequestAdded) {
-      info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+    if (hasNewEntries && prFlowMigrated) {
+      info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
     }
     fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
     ok(`Updated ${CONFIG_PATH}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/hooks/auto-resume.sh

@@ -80,8 +80,25 @@ until curl -s -o /dev/null --max-time 3 "$PROBE_URL"; do
 done
 log "probe ok after ${waited}s (error=$error)"
 
-# Inject: Escape first to leave any non-input TUI state, then the resume text.
-tmux send-keys -t "$TMUX_PANE" Escape 2>/dev/null
-tmux send-keys -t "$TMUX_PANE" "$RESUME_TEXT" Enter 2>/dev/null
-log "send-keys done (error=$error)"
+# Inject the resume message with a deliberately timing-insensitive sequence:
+#   1. Escape leaves any non-input TUI state.
+#   2. A 1s settle covers every known TUI escape timeout (vim 1000ms,
+#      xterm/readline 50ms) so the next bytes are delivered as fresh input
+#      instead of being folded into the escape sequence (the dropped-`U` race).
+#   3. The text travels through a NAMED paste buffer pasted with bracketed
+#      paste (-p): the TUI ingests it as a single paste rather than per-character
+#      keypresses, so no leading char is eaten and the body is not read as a
+#      submit. The named buffer (-b) guarantees we paste exactly this text, and
+#      -d deletes it afterward so the user's anonymous paste stack is untouched.
+#   4. Enter is a separate send-keys after the paste, so the submit signal is
+#      never merged into the pasted content (the must-press-Enter race).
+# Every step stays non-blocking (2>/dev/null, exit 0 below) and logs a WARN on
+# failure so the log can localize which tmux step broke.
+log "tmux inject start (error=$error)"
+tmux send-keys -t "$TMUX_PANE" Escape 2>/dev/null || log "WARN: tmux Escape failed (error=$error)"
+sleep 1
+tmux set-buffer -b auto-resume -- "$RESUME_TEXT" 2>/dev/null || log "WARN: tmux set-buffer failed (error=$error)"
+tmux paste-buffer -t "$TMUX_PANE" -b auto-resume -p -d 2>/dev/null || log "WARN: tmux paste-buffer failed (error=$error)"
+tmux send-keys -t "$TMUX_PANE" Enter 2>/dev/null || log "WARN: tmux Enter failed (error=$error)"
+log "tmux inject done (error=$error)"
 exit 0

package/templates/.agents/rules/next-step-output.en.md

@@ -1,6 +1,9 @@
 # Next-Step Output Rule
 
-When a skill renders "Next steps" commands and the "Task info" block in its notify-user step, present the task ID consistently per this rule. Read this file before rendering next steps.
+This file defines two **independent** rules for a skill's "notify-user / Next steps" output; read this file before rendering the final output and apply both:
+
+1. **Next-step output structure**: how "Next steps" commands and the "Task info" block present the task ID (placeholders / short-id lookup / fallback).
+2. **Agent output trailing line (Completed at)**: the **very last line** of user-facing output, **independent of the "Next steps" block**, applying to normal / error / early-return paths alike.
 
 ## Placeholder semantics
 
@@ -46,9 +49,9 @@ process.stdout.write(hit?("#"+hit[0]):full);
 
 Short ids are always rendered with a `#` prefix as `#NN`, matching how task.md frontmatter renders `short_id`. `#` starts a comment in bash, so pasting example commands depends on the TUI (both the bare numeric `NN` and `#NN` are accepted by `task-short-id.js resolve`).
 
-## Completion timestamp line (Completed at)
+## Agent output trailing line (Completed at)
 
-Every skill that reads this rule and renders "Next steps / Inform user" output appends a single completion-time line as the **very last line** of its user-facing output, so users scanning across tmux windows can tell at a glance which agent finished most recently:
+This section is a standalone rule, **co-equal with the next-step output structure** and **not part of the "Next steps" block**. Every skill that renders user-facing output must append the completion-time line as the **very last line** of that output — including **complete-task, which renders no next-step commands**, and **error / early-return paths** where a precondition is unmet. This lets users scanning across tmux windows tell at a glance which agent finished most recently:
 
 ```text
 Completed at: YYYY-MM-DD HH:mm:ss

package/templates/.agents/rules/next-step-output.zh-CN.md

@@ -1,6 +1,9 @@
 # 下一步输出规则
 
-各 skill 在「告知用户」步骤渲染「下一步」命令与「任务信息」段时，统一按本规则呈现任务 ID 形态。渲染下一步前先读取本文件。
+本文件定义 skill「告知用户 / 下一步」输出的两类**相互独立**的规则；渲染最终输出前先读取本文件并同时落实两者：
+
+1. **下一步输出结构**：「下一步」命令与「任务信息」段如何呈现任务 ID 形态（占位符 / 取短号 / 回退）。
+2. **Agent 输出收尾行（Completed at）**：面向用户输出的**绝对最后一行**，**独立于「下一步」块**，正常 / 错误 / 早退路径都适用。
 
 ## 占位符语义
 
@@ -46,9 +49,9 @@ process.stdout.write(hit?("#"+hit[0]):full);
 
 短号统一渲染为带 `#` 前缀的 `#NN`，与 task.md frontmatter 的 `short_id` 渲染一致。`#` 在 bash 中是注释起始符，示例命令若直接粘贴需视 TUI 而定（裸数字 `NN` 与 `#NN` 都被 `task-short-id.js resolve` 接受）。
 
-## 完成时间收尾行（Completed at）
+## Agent 输出收尾行（Completed at）
 
-所有读取本规则、并向用户渲染「下一步 / 告知用户」输出的 skill，在面向用户输出的**绝对最后一行**统一追加一行完成时间，便于用户在 tmux 多窗口扫视时一眼判断各 Agent 的完成先后：
+本节是与「下一步输出结构」**并列的独立规则**，不隶属于「下一步」块。任何向用户渲染输出的 skill 都必须在面向用户输出的**绝对最后一行**追加完成时间收尾行——包括**声明「不渲染下一步命令」的 complete-task**，以及前置条件未满足而提前 return 的**错误 / 早退路径**。便于用户在 tmux 多窗口扫视时一眼判断各 Agent 的完成先后：
 
 ```text
 Completed at: YYYY-MM-DD HH:mm:ss

package/templates/.agents/rules/pr-checks-commands.en.md

@@ -0,0 +1,5 @@
+# PR Checks Platform Commands
+
+This code platform does not provide built-in pull request check commands.
+
+Platform-specific check monitoring is skipped for custom platforms unless you provide matching `.{platform}.en.md` rule templates. Keep local task artifacts as the source of truth, or install a platform-specific template pack before running the `watch-pr` skill.

package/templates/.agents/rules/pr-checks-commands.github.en.md

@@ -0,0 +1,62 @@
+# PR Checks Platform Commands (GitHub)
+
+Read this file before watching a PR's required checks, resolving a failing run, pulling failure logs, or reading the current branch's PR. The `watch-pr` skill's platform-specific commands live here; the skill body and `reference/` stay platform-agnostic.
+
+## Current Branch PR / Repository Info
+
+```bash
+gh pr view --json number -q .number                  # PR number for the current branch
+gh pr view {pr#} --json headRefOid -q .headRefOid    # PR head SHA
+gh repo view --json nameWithOwner -q .nameWithOwner  # {owner}/{repo}
+```
+
+If `gh` is not authenticated or a command fails, stop or degrade per the calling skill's error handling.
+
+## Watch Required Checks
+
+```bash
+gh pr checks {pr#} --required --watch --fail-fast -i 30 \
+  --json name,bucket,link,workflow
+```
+
+- `--required`: include only checks the repository's branch protection marks as required.
+- `--watch`: block until those checks finish; `--fail-fast`: exit watch on the first failure.
+- `-i 30`: poll every 30 seconds (backoff). **Overall time cap default 30 minutes (1800 seconds)**: use the timeout mechanism that matches the execution environment; on timeout, treat as "pending" (exit code 8).
+  - POSIX shell: `timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
+  - PowerShell (Windows): use a job timeout —
+    ```powershell
+    $job = Start-Job { gh pr checks {pr#} --required --watch --fail-fast -i 30 }
+    if (Wait-Job $job -Timeout 1800) { Receive-Job $job } else { Stop-Job $job; <treat as "pending"> }
+    ```
+  - Platform-neutral fallback (no external timeout tool): record the start time, loop `gh pr checks {pr#} --required --json name,bucket,link,workflow` **without** `--watch`, sleeping `-i` seconds each round and checking whether any `bucket` is still `pending`; if the elapsed time reaches 1800 seconds without finishing, exit the loop and treat as "pending".
+- The `bucket` field of `--json` classifies each check as `pass` / `fail` / `pending` / `skipping` / `cancel`.
+
+Exit code semantics:
+
+| Exit code | Meaning | Outcome class |
+|-----------|---------|---------------|
+| 0 | all required checks passed | all green |
+| 1 | at least one failed / errored | failure |
+| 8 | still pending (watch timed out or was cut off by `timeout`) | pending |
+
+Old `gh` (< 2.93) without `--required`: fall back to `gh pr checks {pr#} --watch --fail-fast` (i.e. "all checks must succeed"), and note this degradation in the help/report and suggest upgrading `gh`.
+
+## Resolve a Failing Run id and Pull Logs
+
+`gh pr checks --json` does not return a run id directly, but it returns each failing check's `link` (a URL to the run/job). Resolve in this deterministic order:
+
+1. Extract from the failing check's `link` via regex: `https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → group 1 is the run id (optional group 2 is the job id).
+2. When `link` is not a run URL or cannot be parsed, query check-runs by head SHA:
+   ```bash
+   sha=$(gh pr view {pr#} --json headRefOid -q .headRefOid)
+   gh api "repos/{owner}/{repo}/commits/$sha/check-runs" \
+     --jq '.check_runs[] | select(.name=="{failed-check-name}") | .details_url'
+   ```
+   then extract the run id from `details_url` the same way.
+3. If neither path yields a run id → treat as "unlocatable" and use the skill's help exit; do not self-heal blindly.
+
+Once the run id is known, pull the failure logs:
+
+```bash
+gh run view {run-id} --log-failed
+```

package/templates/.agents/rules/pr-checks-commands.github.zh-CN.md

@@ -0,0 +1,62 @@
+# PR 检查平台命令（GitHub）
+
+在监控 PR 的 required checks、解析失败 run、拉取失败日志或读取当前分支 PR 前先读取本文件。`watch-pr` 技能的平台专属命令集中在此，技能正文与 `reference/` 保持平台无关。
+
+## 当前分支 PR / 仓库信息
+
+```bash
+gh pr view --json number -q .number          # 当前分支对应的 PR 号
+gh pr view {pr#} --json headRefOid -q .headRefOid   # PR head SHA
+gh repo view --json nameWithOwner -q .nameWithOwner # {owner}/{repo}
+```
+
+`gh` 未认证或命令失败时，按调用方技能的错误处理停止或降级。
+
+## 监控 required checks
+
+```bash
+gh pr checks {pr#} --required --watch --fail-fast -i 30 \
+  --json name,bucket,link,workflow
+```
+
+- `--required`：只纳入仓库分支保护标记为 required 的 checks。
+- `--watch`：阻塞直到这些 checks 全部跑完；`--fail-fast`：出现首个失败即退出 watch。
+- `-i 30`：轮询间隔 30 秒（退避）。**总时长上限默认 30 分钟（1800 秒）**：按执行环境选用对应的超时方式，超时即按「挂起」处理（退出码 8）。
+  - POSIX shell：`timeout 1800 gh pr checks {pr#} --required --watch --fail-fast -i 30 …`
+  - PowerShell（Windows）：用作业超时——
+    ```powershell
+    $job = Start-Job { gh pr checks {pr#} --required --watch --fail-fast -i 30 }
+    if (Wait-Job $job -Timeout 1800) { Receive-Job $job } else { Stop-Job $job; <按「挂起」处理> }
+    ```
+  - 平台中立回退（无外部超时工具时）：记录开始时间，循环执行**不带** `--watch` 的 `gh pr checks {pr#} --required --json name,bucket,link,workflow`，每轮 sleep `-i` 秒并检查 `bucket` 是否仍有 `pending`；累计时长 ≥ 1800 秒仍未结束 → 退出循环按「挂起」处理。
+- `--json` 的 `bucket` 字段把每个 check 归类为 `pass` / `fail` / `pending` / `skipping` / `cancel`。
+
+退出码语义：
+
+| 退出码 | 含义 | 结果分类 |
+|--------|------|----------|
+| 0 | 全部 required checks 通过 | 全绿 |
+| 1 | 至少一个失败 / 出错 | 失败 |
+| 8 | 仍有 pending（watch 超时或被 `timeout` 截断） | 挂起 |
+
+旧版 `gh`（< 2.93）若不支持 `--required`：回退为 `gh pr checks {pr#} --watch --fail-fast`（即「所有 check 必须 success」），并在求助/报告中注明该降级、建议升级 `gh`。
+
+## 解析失败 run id 并拉日志
+
+`gh pr checks --json` 不直接返回 run id，但返回失败 check 的 `link`（指向 run/job 的 URL）。按确定性顺序解析：
+
+1. 从失败 check 的 `link` 用正则提取：`https://github.com/{owner}/{repo}/actions/runs/(\d+)(?:/job/(\d+))?` → 第 1 组为 run id（可选第 2 组为 job id）。
+2. `link` 非 run URL 或无法解析时，用 head SHA 查 check-runs：
+   ```bash
+   sha=$(gh pr view {pr#} --json headRefOid -q .headRefOid)
+   gh api "repos/{owner}/{repo}/commits/$sha/check-runs" \
+     --jq '.check_runs[] | select(.name=="{failed-check-name}") | .details_url'
+   ```
+   再从 `details_url` 同法提取 run id。
+3. 两路都拿不到 run id → 视为「不可定位」，按技能的求助出口处理，不盲目自愈。
+
+拿到 run id 后拉失败日志：
+
+```bash
+gh run view {run-id} --log-failed
+```

package/templates/.agents/rules/pr-checks-commands.zh-CN.md

@@ -0,0 +1,5 @@
+# PR 检查平台命令
+
+当前代码平台未内置 Pull Request 检查命令支持。
+
+自定义平台会跳过平台专属的检查监控，除非你提供匹配的 `.{platform}.zh-CN.md` 规则模板。请以本地任务产物作为事实来源，或先安装平台专属模板包再运行 `watch-pr` 技能。

package/templates/.agents/rules/pr-sync.github.en.md

@@ -32,6 +32,7 @@ Aggregation rules:
 - build the review-history table from `review-code*` and `code*`
 - extract the test summary from `code*`
 - if one artifact class is missing, treat it as "no data for this stage" and continue
+- Manual verification section: extract items requiring human confirmation/fallback from the "Assumptions"/"Open Questions" of the latest `plan*` and the "Environment-Blocked Findings"/"Self-Doubt" sections (i.e. env-blocked items) of the latest `review-code*`; when there are none, write the explicit placeholder `- None — no items require manual verification`, never leave it empty
 
 ## Comment Body Template
 
@@ -46,6 +47,12 @@ Use this canonical comment body template:
 
 **Updated At**: {current-time}
 
+### ⚠️ Manual Verification Required
+
+> Items in this change that need human confirmation/fallback; reviewers can reply under this comment once verified.
+
+- {manual-verify-item}
+
 ### Key Technical Decisions
 
 - {decision-1}

package/templates/.agents/rules/pr-sync.github.zh-CN.md

@@ -32,6 +32,7 @@
 - 用 `review-code*` 与 `code*` 构建审查历程表
 - 从 `code*` 提取测试结果摘要
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
+- 需人工校验段落：从最新 `plan*` 的「假设」「未决问题」与最新 `review-code*` 的「环境性遗留」「自我质疑」提取需人工确认/兜底事项；无任何事项时写显式占位 `- 无需人工校验事项`，不得留空
 
 ## 评论体模板
 
@@ -46,6 +47,12 @@
 
 **更新时间**：{当前时间}
 
+### ⚠️ 需人工校验
+
+> 本次改动中需人工确认/兜底的事项；reviewer 校验后可在本评论下回复收尾。
+
+- {manual-verify-item}
+
 ### 关键技术决策
 
 - {decision-1}

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

@@ -189,7 +189,7 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
 
 Output format:
 ```

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

@@ -188,7 +188,7 @@ node .agents/scripts/validate-artifact.js gate analyze-task .agents/workspace/ac
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
 
 输出格式：
 ```

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

@@ -106,7 +106,9 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+
+> **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.
 
 Output format:
 ```
@@ -116,6 +118,11 @@ Blocking reason: {summary}
 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}
+
 To unblock when the issue is resolved:
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # Then update task.md: status -> active, remove blocked_at

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

@@ -105,7 +105,9 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「归档路径」之后、「解除阻塞时执行」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 blocked/，从 `.agents/workspace/blocked/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
 ```
@@ -115,6 +117,11 @@ node .agents/scripts/validate-artifact.js gate block-task .agents/workspace/bloc
 解除阻塞所需：{需要什么}
 归档路径：.agents/workspace/blocked/{task-id}/
 
+可选：清理本任务的沙箱
+（任务已阻塞并移到 blocked/，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
 解除阻塞时执行：
   mv .agents/workspace/blocked/{task-id} .agents/workspace/active/{task-id}
   # 然后更新 task.md：status -> active，移除 blocked_at

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

@@ -119,7 +119,9 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 
 > Execute this step only after the verification gate passes.
 
-> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the "Next steps" commands, read `.agents/rules/next-step-output.md` and use its short-id snippet to render `{task-ref}` in the commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released).
+> **IMPORTANT**: All TUI command formats listed below must be output in full. Do not show only the format for the current AI agent. If `.agents/.airc.json` configures custom TUIs (via `customTUIs`), read each tool's `name` and `invoke`, then add the matching command line in the same format (`${skillName}` becomes the skill name and `${projectName}` becomes the project name). Before rendering the final output, read `.agents/rules/next-step-output.md` and apply both of its rules: (1) render `{task-ref}` in the "Next steps" commands as the short id `#NN` (falling back to the full TASK-id when unallocated or released); (2) append the `Completed at` line as the very last line of the user-facing output (this applies to every user-facing output — success, error, and early-return paths alike, not only the success path).
+
+> **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.
 
 Output format:
 ```
@@ -129,6 +131,11 @@ Cancellation reason: {reason}
 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:)
+
+ai sandbox rm {branch}
+
 Next step - inspect the moved task:
   - Claude Code / OpenCode: /check-task {task-ref}
   - Gemini CLI: /{{project}}:check-task {task-ref}

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

@@ -118,7 +118,9 @@ node .agents/scripts/validate-artifact.js gate cancel-task .agents/workspace/com
 
 > 仅在校验通过后执行本步骤。
 
-> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染「下一步」命令前，先读取 `.agents/rules/next-step-output.md`，按其取短号片段把命令中的 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）。
+> **重要**：以下「下一步」中列出的所有 TUI 命令格式必须完整输出，不要只展示当前 AI 代理对应的格式。如果 `.agents/.airc.json` 中配置了自定义 TUI（`customTUIs`），读取每个工具的 `name` 和 `invoke`，按同样格式补充对应命令行（`${skillName}` 替换为技能名，`${projectName}` 替换为项目名）。 渲染最终输出前，先读取 `.agents/rules/next-step-output.md` 并落实其两类规则：(1) 「下一步」命令把 `{task-ref}` 渲染为短号 `#NN`（未分配/已释放时回退完整 TASK-id）；(2) 在面向用户输出的绝对最后一行追加 `Completed at` 收尾行（成功、错误、早退等任何面向用户输出都适用，不限于校验通过的成功态）。
+
+> **可选沙箱清理提示（门控渲染）**：仅当同时满足 (1) `.agents/.airc.json` 存在 `sandbox` 字段、(2) task.md 的 `branch` 字段存在且不是 `main` / `master` 时，才渲染下方输出中「目标路径」之后、「下一步」之前的「可选：清理本任务的沙箱」块；任一不满足则整段省略。`{branch}` 取已读入的 task.md 的 `branch` 值（任务此时已移动到 completed/，从 `.agents/workspace/completed/{task-id}/task.md` 读取）。该块独立于「下一步」语义。
 
 输出格式：
 ```
@@ -128,6 +130,11 @@ node .agents/scripts/validate-artifact.js gate cancel-task .agents/workspace/com
 状态标签：{status-label 或 skipped}
 目标路径：.agents/workspace/completed/{task-id}/
 
+可选：清理本任务的沙箱
+（任务已归档，沙箱容器和 per-branch 配置目录不会自动回收。如果不再需要可执行：）
+
+ai sandbox rm {branch}
+
 下一步 - 查看已转移任务：
   - Claude Code / OpenCode：/check-task {task-ref}
   - Gemini CLI：/{{project}}:check-task {task-ref}