@fitlab-ai/agent-infra 0.8.0 → 0.8.2

package/lib/task/commands/status.ts

@@ -1,24 +1,27 @@
 import fs from 'node:fs';
+import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { commandForEngine } from '../../sandbox/shell.ts';
 import { resolveTaskRef } from '../resolve-ref.ts';
 import { enumerateArtifacts, type Artifact } from '../artifacts.ts';
 import { parseTaskFrontmatter, extractTitle, type Frontmatter } from '../frontmatter.ts';
 import { loadShortIdByTaskId } from '../short-id.ts';
+import { parseActivityLog, pairEntries } from './log.ts';
 
 const USAGE = `Usage: ai task status <N | #N | TASK-id>
 
-Prints an aggregated "health check" view for a task: header, metadata, an
-artifacts summary, git branch state, and best-effort GitHub issue/PR status.
+Prints an aggregated "health check" view for a task: header, metadata,
+artifacts, workflow/runtime execution state, and git branch state.
   <ref>   Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
 
-Git and Platform rows are best-effort: a failed git/gh call degrades that row to
-'-' without failing the command.
+Git rows are best-effort: a failed git call degrades that row to '-' without
+failing the command.
 `;
 
 const DASH = '-';
 
 // Subprocess boundary: the single place this command shells out. Injectable so
-// the collectors below can be unit-tested without spawning git/gh. Returns the
+// the collectors below can be unit-tested without spawning git. Returns the
 // command's stdout; throws (like execFileSync) on a non-zero exit or spawn error.
 type Runner = (file: string, args: string[]) => string;
 
@@ -27,7 +30,7 @@ function makeRunner(cwd: string): Runner {
     execFileSync(file, args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
 }
 
-// Run `run` and swallow any failure into null, so a single failing git/gh call
+// Run `run` and swallow any failure into null, so a single failing git call
 // degrades only its own field instead of aborting the whole view.
 function tryRun(run: Runner, file: string, args: string[]): string | null {
   try {
@@ -47,9 +50,7 @@ const METADATA_KEYS = [
   'branch',
   'assigned_to',
   'created_at',
-  'updated_at',
-  'issue_number',
-  'pr_status'
+  'updated_at'
 ] as const;
 
 function collectMetadata(fm: Frontmatter): [string, string][] {
@@ -155,55 +156,176 @@ function collectGit(frontmatterBranch: string, run: Runner): GitInfo {
   return { current, frontmatter, match, exists, uncommitted, aheadBehind };
 }
 
-type PlatformInfo = { issue: string; pr: string };
-
-function collectPlatform(fm: Frontmatter, run: Runner): PlatformInfo {
-  let issue = DASH;
-  if (fm.issue_number && /^\d+$/.test(fm.issue_number)) {
-    const out = tryRun(run, 'gh', ['issue', 'view', fm.issue_number, '--json', 'state,labels']);
-    if (out !== null) {
-      try {
-        const data = JSON.parse(out);
-        const labels = Array.isArray(data.labels)
-          ? data.labels.map((label: { name: string }) => label.name).join(', ')
-          : '';
-        issue = labels ? `${data.state} [${labels}]` : `${data.state}`;
-      } catch {
-        issue = DASH;
-      }
-    }
+type WorkflowInfo = {
+  state: string;
+  step: string;
+  agent: string;
+  startedAt: string;
+  doneAt: string;
+  stale: string;
+};
+
+const STALE_MS = 60 * 60 * 1000;
+
+function parseActivityTime(value: string): number {
+  const epoch = Date.parse(value.replace(' ', 'T'));
+  return Number.isFinite(epoch) ? epoch : Number.NaN;
+}
+
+function collectWorkflow(content: string, now: Date = new Date()): WorkflowInfo {
+  const parsed = parseActivityLog(content);
+  if (!parsed.sectionFound || parsed.entries.length === 0) {
+    return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
+  }
+
+  const rows = pairEntries(parsed.entries);
+  const latest = rows.at(-1);
+  if (!latest) {
+    return { state: 'unknown', step: DASH, agent: DASH, startedAt: DASH, doneAt: DASH, stale: DASH };
   }
 
-  let pr = DASH;
-  if (fm.pr_status === 'created' && fm.pr_number && /^\d+$/.test(fm.pr_number)) {
-    const out = tryRun(run, 'gh', ['pr', 'view', fm.pr_number, '--json', 'state,statusCheckRollup']);
-    if (out !== null) {
-      try {
-        const data = JSON.parse(out);
-        const rollup = Array.isArray(data.statusCheckRollup) ? data.statusCheckRollup : [];
-        const passed = rollup.filter(
-          (check: { conclusion?: string; state?: string }) =>
-            check.conclusion === 'SUCCESS' || check.state === 'SUCCESS'
-        ).length;
-        pr = rollup.length > 0 ? `${data.state}, checks: ${passed}/${rollup.length}` : `${data.state}`;
-      } catch {
-        pr = DASH;
+  const inProgress = latest.started !== '' && latest.done === '';
+  const state = inProgress ? 'in-progress' : latest.done ? 'idle' : 'unknown';
+  let stale = DASH;
+  if (inProgress) {
+    const started = parseActivityTime(latest.started);
+    stale = Number.isFinite(started) ? (now.getTime() - started > STALE_MS ? 'yes' : 'no') : 'unknown';
+  }
+
+  return {
+    state,
+    step: latest.step || DASH,
+    agent: latest.agent || DASH,
+    startedAt: latest.started || DASH,
+    doneAt: latest.done || DASH,
+    stale
+  };
+}
+
+type RuntimeInfo = {
+  mode: string;
+  status: string;
+  run: string;
+  tmux: string;
+  startedAt: string;
+  finishedAt: string;
+  exitCode: string;
+  log: string;
+};
+
+type ManagedRunRecord = {
+  run_id: string;
+  engine: string;
+  container: string;
+  run_dir: string;
+  status_file: string;
+  log_file: string;
+};
+
+function latestRunRecord(taskDir: string): ManagedRunRecord | null {
+  const runsDir = path.join(taskDir, 'runs');
+  if (!fs.existsSync(runsDir)) return null;
+  const candidates: { path: string; mtimeMs: number }[] = [];
+  for (const entry of fs.readdirSync(runsDir)) {
+    if (!entry.endsWith('.json')) continue;
+    const filePath = path.join(runsDir, entry);
+    const stat = fs.statSync(filePath);
+    if (stat.isFile()) candidates.push({ path: filePath, mtimeMs: stat.mtimeMs });
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  for (const candidate of candidates) {
+    try {
+      const data = JSON.parse(fs.readFileSync(candidate.path, 'utf8'));
+      if (
+        typeof data?.run_id === 'string' &&
+        typeof data?.engine === 'string' &&
+        typeof data?.container === 'string' &&
+        typeof data?.run_dir === 'string'
+      ) {
+        return {
+          run_id: data.run_id,
+          engine: data.engine,
+          container: data.container,
+          run_dir: data.run_dir,
+          status_file:
+            typeof data.status_file === 'string' ? data.status_file : `${data.run_dir}/status`,
+          log_file:
+            typeof data.log_file === 'string' ? data.log_file : `${data.run_dir}/output.log`
+        };
       }
+    } catch {
+      // Ignore malformed local records and try the next newest file.
     }
   }
 
-  return { issue, pr };
+  return null;
+}
+
+function readRuntimeFile(record: ManagedRunRecord, filePath: string, run: Runner): string | null {
+  const command = commandForEngine(record.engine, 'docker', ['exec', record.container, 'cat', filePath]);
+  const output = tryRun(run, command.cmd, command.args);
+  return output === null ? null : output.trim();
+}
+
+function runtimeValue(record: ManagedRunRecord, name: string, run: Runner): string {
+  const output = readRuntimeFile(record, `${record.run_dir}/${name}`, run);
+  return output ? output : DASH;
+}
+
+function collectRuntime(taskDir: string, workflow: WorkflowInfo, run: Runner): RuntimeInfo {
+  const record = latestRunRecord(taskDir);
+  if (!record) {
+    return workflow.state === 'in-progress'
+      ? {
+          mode: 'unmanaged',
+          status: 'inferred-from-workflow',
+          run: DASH,
+          tmux: DASH,
+          startedAt: DASH,
+          finishedAt: DASH,
+          exitCode: DASH,
+          log: DASH
+        }
+      : {
+          mode: 'none',
+          status: DASH,
+          run: DASH,
+          tmux: DASH,
+          startedAt: DASH,
+          finishedAt: DASH,
+          exitCode: DASH,
+          log: DASH
+        };
+  }
+
+  const status = readRuntimeFile(record, record.status_file, run)?.trim() || 'unknown';
+  const session = runtimeValue(record, 'session', run);
+  const window = runtimeValue(record, 'window', run);
+  const pane = runtimeValue(record, 'pane', run);
+  const tmux = session !== DASH && window !== DASH && pane !== DASH ? `${session}:${window}:${pane}` : DASH;
+
+  return {
+    mode: 'managed-tmux',
+    status,
+    run: record.run_id,
+    tmux,
+    startedAt: runtimeValue(record, 'started_at', run),
+    finishedAt: runtimeValue(record, 'finished_at', run),
+    exitCode: runtimeValue(record, 'exit_code', run),
+    log: record.log_file
+  };
 }
 
 type StatusModel = {
   taskId: string;
   shortId: string;
   title: string;
-  issueNumber: string;
   metadata: [string, string][];
   artifacts: { count: number; groups: { stage: string; files: string[] }[] };
+  workflow: WorkflowInfo;
+  runtime: RuntimeInfo;
   git: GitInfo;
-  platform: PlatformInfo;
 };
 
 // Indent each label/value pair by two spaces and pad labels to a common width so
@@ -228,6 +350,34 @@ function renderStatus(model: StatusModel): string[] {
     lines.push(...renderPairs(model.artifacts.groups.map((group) => [group.stage, group.files.join(', ')])));
   }
 
+  lines.push(
+    '',
+    'Workflow',
+    ...renderPairs([
+      ['state', model.workflow.state],
+      ['step', model.workflow.step],
+      ['agent', model.workflow.agent],
+      ['started_at', model.workflow.startedAt],
+      ['done_at', model.workflow.doneAt],
+      ['stale', model.workflow.stale]
+    ])
+  );
+
+  lines.push(
+    '',
+    'Runtime',
+    ...renderPairs([
+      ['mode', model.runtime.mode],
+      ['status', model.runtime.status],
+      ['run', model.runtime.run],
+      ['tmux', model.runtime.tmux],
+      ['started_at', model.runtime.startedAt],
+      ['finished_at', model.runtime.finishedAt],
+      ['exit_code', model.runtime.exitCode],
+      ['log', model.runtime.log]
+    ])
+  );
+
   lines.push(
     '',
     'Git',
@@ -241,16 +391,6 @@ function renderStatus(model: StatusModel): string[] {
     ])
   );
 
-  const issueLabel = model.issueNumber ? `issue #${model.issueNumber}` : 'issue';
-  lines.push(
-    '',
-    'Platform',
-    ...renderPairs([
-      [issueLabel, model.platform.issue],
-      ['pr', model.platform.pr]
-    ])
-  );
-
   return lines;
 }
 
@@ -272,16 +412,17 @@ function status(args: string[] = []): void {
   const fm = parseTaskFrontmatter(content);
   const run = makeRunner(resolved.repoRoot);
   const artifacts = enumerateArtifacts(resolved.taskDir);
+  const workflow = collectWorkflow(content);
 
   const model: StatusModel = {
     taskId: resolved.taskId,
     shortId: loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId) ?? DASH,
     title: extractTitle(content),
-    issueNumber: fm.issue_number && /^\d+$/.test(fm.issue_number) ? fm.issue_number : '',
     metadata: collectMetadata(fm),
     artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
-    git: collectGit(fm.branch ?? '', run),
-    platform: collectPlatform(fm, run)
+    workflow,
+    runtime: collectRuntime(resolved.taskDir, workflow, run),
+    git: collectGit(fm.branch ?? '', run)
   };
 
   for (const line of renderStatus(model)) {
@@ -295,8 +436,9 @@ export {
   collectMetadata,
   groupArtifacts,
   collectGit,
-  collectPlatform,
+  collectWorkflow,
+  collectRuntime,
   renderStatus,
   METADATA_KEYS
 };
-export type { Runner, GitInfo, PlatformInfo, StatusModel };
+export type { Runner, GitInfo, WorkflowInfo, RuntimeInfo, StatusModel };

package/lib/update.ts

@@ -40,6 +40,9 @@ const defaults = JSON.parse(
 
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
+const AGENT_INFRA_SANDBOX_TOOL = 'agent-infra';
+const LEGACY_DEFAULT_SANDBOX_TOOLS = ['claude-code', 'codex', 'gemini-cli', 'opencode'];
+const DEFAULT_SANDBOX_TOOLS = [AGENT_INFRA_SANDBOX_TOOL, ...LEGACY_DEFAULT_SANDBOX_TOOLS];
 
 // 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
@@ -60,6 +63,26 @@ function migratePrFlow(config: UpdateConfig): 'required' | 'disabled' | null {
   return null;
 }
 
+function isLegacyDefaultSandboxTools(value: unknown): value is string[] {
+  if (!Array.isArray(value) || value.length !== LEGACY_DEFAULT_SANDBOX_TOOLS.length) {
+    return false;
+  }
+  const tools = new Set(value);
+  return LEGACY_DEFAULT_SANDBOX_TOOLS.every((tool) => tools.has(tool));
+}
+
+function migrateSandboxTools(config: UpdateConfig): boolean {
+  const tools = config.sandbox?.tools;
+  if (!isLegacyDefaultSandboxTools(tools)) {
+    return false;
+  }
+  config.sandbox = {
+    ...config.sandbox,
+    tools: [...DEFAULT_SANDBOX_TOOLS]
+  };
+  return true;
+}
+
 function isPathOwnedByOtherPlatform(relativePath: string, platformType: string): boolean {
   const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
   if (!top.startsWith('.')) return false;
@@ -215,6 +238,7 @@ async function cmdUpdate(): Promise<void> {
   const taskAdded = !config.task;
   const labelsAdded = !config.labels;
   const prFlowMigrated = migratePrFlow(config);
+  const sandboxToolsMigrated = !sandboxAdded && migrateSandboxTools(config);
   let configChanged = changed;
 
   if (platformAdded) {
@@ -241,6 +265,10 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
+  if (sandboxToolsMigrated) {
+    configChanged = true;
+  }
+
   if (configChanged) {
     console.log('');
     if (hasNewEntries) {
@@ -267,6 +295,9 @@ async function cmdUpdate(): Promise<void> {
       if (prFlowMigrated) {
         info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
       }
+      if (sandboxToolsMigrated) {
+        info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} in ${CONFIG_PATH}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -285,6 +316,9 @@ async function cmdUpdate(): Promise<void> {
     if (hasNewEntries && prFlowMigrated) {
       info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && sandboxToolsMigrated) {
+      info(`Migrated default sandbox.tools to include ${AGENT_INFRA_SANDBOX_TOOL} 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.8.0",
+  "version": "0.8.2",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -29,7 +29,7 @@
     "templates/"
   ],
   "engines": {
-    "node": ">=22"
+    "node": ">=22.9.0"
   },
   "keywords": [
     "ai",
@@ -43,7 +43,7 @@
     "installer"
   ],
   "dependencies": {
-    "@clack/prompts": "1.6.0",
+    "@clack/prompts": "1.7.0",
     "@larksuiteoapi/node-sdk": "^1.68.0",
     "cross-spawn": "^7.0.6",
     "picocolors": "1.1.1",
@@ -58,13 +58,14 @@
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
     "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\"",
     "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "check": "npm run typecheck && npm test",
     "test": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\"",
     "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
     "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\""
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^24.0.0",
+    "@types/node": "^22.20.0",
     "@types/semver": "^7.7.1",
     "typescript": "~6.0"
   },

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

@@ -260,7 +260,7 @@ Supported `invoke` placeholders:
 | Placeholder | Replaced with | Example |
 |-------------|---------------|---------|
 | `${skillName}` | The skill command name, such as `review-code` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
-| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/your-project:review-code` |
 
 Non-namespaced custom TUI:
 
@@ -280,7 +280,7 @@ Namespaced custom TUI:
 
 ```json
 {
-  "project": "agent-infra",
+  "project": "your-project",
   "customTUIs": [
     {
       "name": "<your-tui-name>",
@@ -295,7 +295,7 @@ Namespaced custom TUI:
 
 ## Sandbox Custom Tools
 
-`customTUIs` (above) generates slash-command files but does not change the sandbox image. To install a non-npm TUI (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in tools (`claude-code`, `codex`, `opencode`, `gemini-cli`) keep working unchanged.
+`customTUIs` generates slash-command files but does not change the sandbox image. To install a non-npm CLI or tool (pip / cargo / curl-based / pre-built binary) into the sandbox image and live-mount its credentials, declare it under `sandbox.customTools` in `.agents/.airc.json`. Built-in sandbox tools (`claude-code`, `codex`, `opencode`, `gemini-cli`, `agent-infra`) keep working unchanged; `agent-infra` only provides the in-sandbox `ai` / `agent-infra` CLI and is not part of `tuis` or `customTUIs`.
 
 ### Required fields
 

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

@@ -260,7 +260,7 @@ args: "<task-id>"   # 可选
 | 占位符 | 替换为 | 示例 |
 |--------|--------|------|
 | `${skillName}` | skill 命令名，例如 `review-code` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
-| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/your-project:review-code` |
 
 不带命名空间的自定义 TUI：
 
@@ -280,7 +280,7 @@ args: "<task-id>"   # 可选
 
 ```json
 {
-  "project": "agent-infra",
+  "project": "your-project",
   "customTUIs": [
     {
       "name": "<your-tui-name>",
@@ -295,7 +295,7 @@ args: "<task-id>"   # 可选
 
 ## 沙箱自定义工具（Sandbox Custom Tools）
 
-上文 `customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 TUI（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建的四个工具（`claude-code` / `codex` / `opencode` / `gemini-cli`）行为保持不变。
+`customTUIs` 只负责生成 slash-command 文件，**不影响沙箱镜像**。如果要把一个非 npm 分发的 CLI 或工具（pip / cargo / curl 脚本 / 裸二进制）装进沙箱镜像、并 live-mount 它的凭证目录，需要在 `.agents/.airc.json` 的 `sandbox.customTools` 中声明。内建 sandbox 工具（`claude-code` / `codex` / `opencode` / `gemini-cli` / `agent-infra`）行为保持不变；其中 `agent-infra` 只提供沙箱内 `ai` / `agent-infra` CLI，不属于 `tuis` 或 `customTUIs` 配置。
 
 ### 必填字段
 

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

@@ -59,7 +59,7 @@ Completed at: YYYY-MM-DD HH:mm:ss
 ```
 
 - Value command (local timezone, no offset): `date "+%Y-%m-%d %H:%M:%S"`
-- Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the env-blocked reminder), the completion line goes after that reminder.
+- Position: it must be the last line of the entire user-facing output, after all "Next steps" commands. If a scenario has a conditional reminder line after the commands (e.g. the manual-validation reminder), the completion line goes after that reminder.
 - This line is for terminal scanning only; it is never written to any artifact file or Issue/PR comment. The single source of truth for completion time remains the Activity Log in task.md.
 
 ## Pending human-decision pre-block (review-* only, when {h} > 0)

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

@@ -59,7 +59,7 @@ Completed at: YYYY-MM-DD HH:mm:ss
 ```
 
 - 取值命令（本地时区、不带偏移）：`date "+%Y-%m-%d %H:%M:%S"`
-- 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 env-blocked 提醒），收尾行排在该提醒行之后。
+- 位置：必须是整段面向用户输出的最后一行，排在所有「下一步」命令之后。若某场景在命令之后还有条件性提醒行（如 manual-validation 提醒），收尾行排在该提醒行之后。
 - 该行只用于终端扫视，不写入任何产物文件或 Issue/PR 评论；完成时刻的单一事实源仍是 task.md 的 Activity Log。
 
 ## 人工裁决待办前置块（review-* 专用，{h} > 0 时）

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

@@ -34,7 +34,7 @@ Aggregation rules:
 - if one artifact class is missing, treat it as "no data for this stage" and continue
 - Manual verification section: include only post-code-stage checks that still require a human to execute or judge and that the AI cannot close on its own.
   - **Admission boundary**: the verification result depends on a real environment, permissions, account, external system, or human judgment, and cannot be closed by an agent rerunning tests, adding checks, or continuing the fix loop.
-  - **Sources**: `review-code*` "Environment-Blocked Findings", plus `code*` items that satisfy the boundary above.
+  - **Sources**: `review-code*` "Manual Validation Items", plus `code*` items that satisfy the boundary above.
   - **Wording**: each retained item must state at least "what to verify + location (file/change/scope) + why only a human can verify it".
   - **Empty rendering**: when there are no retained items, do NOT use the ⚠️ alarm style (it falsely implies a problem). Render the whole block as: heading `### ✅ No Manual Verification Needed` and a single line `No items in this change require manual confirmation.`, with no item list. Only use the `### ⚠️ Manual Verification Required` heading + item list when retained items exist.
 
@@ -51,7 +51,7 @@ Use this canonical comment body template:
 
 **Updated At**: {current-time}
 
-{manual-verify-section}
+{manual-validation-section}
 
 ### Key Technical Decisions
 
@@ -72,7 +72,7 @@ Use this canonical comment body template:
 *Generated by {agent} · Internal tracking: {task-id}*
 ```
 
-> Render `{manual-verify-section}` per the "manual verification section" aggregation rule above: with retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; with none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
+> Render `{manual-validation-section}` per the "manual verification section" aggregation rule above: with retained items → `### ⚠️ Manual Verification Required` heading + quote + item list; with none → `### ✅ No Manual Verification Needed` heading + a single line `No items in this change require manual confirmation.` (no ⚠️, no list).
 
 ## Comment Lookup And Update
 

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

@@ -34,7 +34,7 @@
 - 某一类产物缺失时，按“无该阶段数据”处理并继续生成
 - 需人工校验段落：只收进入 code 阶段后仍需人实际执行或判断、AI 无法自行关闭的校验点。
   - **准入边界**：校验结论依赖真实环境、权限、账号、外部系统或人工判断，且无法通过 agent 重跑测试、补充检查或继续修复自行关闭。
-  - **来源**：`review-code*` 的「环境性遗留」，以及 `code*` 中满足上述边界的校验点。
+  - **来源**：`review-code*` 的「人工校验项」，以及 `code*` 中满足上述边界的校验点。
   - **写法**：每条保留项至少写明「校验什么 + 定位（文件/改动/范围）+ 为什么只能由人校验」。
   - **空集渲染**：无保留项时，不要使用 ⚠️ 告警样式（会让人误以为有问题）。整段降级渲染为：标题 `### ✅ 无需人工校验`，正文一行 `本次改动无需人工确认事项。`，不带条目列表。有保留项时才用 `### ⚠️ 需人工校验` 标题 + 条目列表。
 
@@ -51,7 +51,7 @@
 
 **更新时间**：{当前时间}
 
-{manual-verify-section}
+{manual-validation-section}
 
 ### 关键技术决策
 
@@ -72,7 +72,7 @@
 *由 {agent} 自动生成 · 内部追踪：{task-id}*
 ```
 
-> `{manual-verify-section}` 按上文「需人工校验段落」聚合规则渲染：有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
+> `{manual-validation-section}` 按上文「需人工校验段落」聚合规则渲染：有保留项 → `### ⚠️ 需人工校验` 标题 + 引用说明 + 条目列表；无保留项 → `### ✅ 无需人工校验` 标题 + 一行 `本次改动无需人工确认事项。`（不带 ⚠️、不带列表）。
 
 ## 评论查找与更新
 

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

@@ -52,7 +52,7 @@ Map user intent to the corresponding workflow command:
 
 **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.
 
-**Human counts** (`ai task log`): review step rows fold two human counts into the NOTE verdict text, comma-separated, right after `blockers/major/minor`, with fixed English labels `Manual-verify: {e}, Human-decision: {h}`. `Human-decision` (`{h}`) maps canonical step prefixes (`Review Analysis` / `Review Plan` / `Review Code`) to `analysis` / `plan` / `code`, then counts current rows in `## Review Disagreement Ledger` / `## 审查分歧账本` for that stage with `status ∈ {needs-human-decision, human-decided}`. `Manual-verify` (`{e}`) parses `(+ {n} env-blocked)` from the review done note (de-duplicated from the display), defaulting to `0`. Non-review rows carry no human counts.
+**Human counts** (`ai task log`): review step rows fold two human counts into the NOTE verdict text, comma-separated, right after `blockers/major/minor`, with fixed English labels `Manual-validation: {e}, Human-decision: {h}`. `Human-decision` (`{h}`) maps canonical step prefixes (`Review Analysis` / `Review Plan` / `Review Code`) to `analysis` / `plan` / `code`, then counts current rows in `## Review Disagreement Ledger` / `## 审查分歧账本` for that stage with `status ∈ {needs-human-decision, human-decided}`. `Manual-validation` (`{e}`) parses the `Manual-validation: {n}` source field from the review done note (normalized to the same field when displayed), defaulting to `0`. Non-review rows carry no human counts.
 
 **Gate** (`checkActivityLog`): when computing the "latest action / freshness" it skips `[started]` lines (ascending-order and format checks still cover every line), so a started marker never satisfies a skill's `expected_action_pattern`.
 

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

@@ -56,7 +56,7 @@
 
 **配对与渲染**（`ai task log`）：按 `{基名}` 把 started 与其后最近的同名 done 配成一行（同基名多次执行按时间升序 FIFO 配对）。STARTED 列显示 started 时间、DONE 列显示 done 时间；只有 started 无 done = 进行中（DONE 显示 `(in progress)`）；只有 done 无 started（历史日志）= 单态完成行。三种形态都合法、不报错。
 
-**人工计数**（`ai task log`）：审查步骤行把两项人工计数并入 NOTE 的 verdict 文本，逗号分隔、紧随 `blockers/major/minor`，固定英文标签 `Manual-verify: {e}, Human-decision: {h}`。`Human-decision`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`Manual-verify`（`{e}`）解析 review done note 中的 `(+ {n} env-blocked)`（解析后从展示中去重），缺失为 `0`。非审查步骤不附加人工计数。
+**人工计数**（`ai task log`）：审查步骤行把两项人工计数并入 NOTE 的 verdict 文本，逗号分隔、紧随 `blockers/major/minor`，固定英文标签 `Manual-validation: {e}, Human-decision: {h}`。`Human-decision`（`{h}`）按 canonical 步骤名前缀（`Review Analysis` / `Review Plan` / `Review Code`）映射到 `analysis` / `plan` / `code`，统计 `## 审查分歧账本` 中对应阶段 `status ∈ {needs-human-decision, human-decided}` 的当前累计数量；`Manual-validation`（`{e}`）解析 review done note 中的 `Manual-validation: {n}` 源字段（展示时归一化为同一字段），缺失为 `0`。非审查步骤不附加人工计数。
 
 **gate**（`checkActivityLog`）：计算「最新 action / freshness」时跳过 `[started]` 行（升序与格式校验仍覆盖全部行），故 started 标记不会污染各 SKILL 的 `expected_action_pattern`。
 

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

@@ -12,7 +12,7 @@ Implement the approved plan and produce `code.md` or `code-r{N}.md`. This skill
 ## Boundary / Critical Rules
 
 - Follow the latest plan artifact: `plan.md` or `plan-r{N}.md`
-- Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; env-blocked items are out of scope
+- Fix mode verifies each finding of the latest `review-code` one by one: fix it if it holds, or rebut it and record it under unresolved if it is unfounded/hallucinated; do not expand to issues the review did not list; manual-validation items are out of scope
 - If implementation encounters a key design decision not covered by the plan, per `.agents/rules/no-mid-flow-questions.md` write its detail block into the implementation report's `## 人工裁决待办` (Pending Human Decisions) section as `### HD-N：<title> [needs-human-decision]` (`HD-N` is globally unique, see `.agents/rules/review-handshake.md`) and write the matching `HD-` ledger row, instead of asking mid-flow or expanding scope silently
 - Never auto-run `git add` or `git commit`
 - Create a new code artifact for each round and never overwrite an older one

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

@@ -12,7 +12,7 @@ description: >
 ## 行为边界 / 关键规则
 
 - 严格遵循最新方案产物：`plan.md` 或 `plan-r{N}.md`
-- 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；env-blocked 项不在修复范围
+- 修复模式逐条核实最新 `review-code` 的发现：成立则修复，判定为不成立/幻觉则在报告中反驳并记入 unresolved；不擅自扩大到审查未列出的问题；manual-validation 项不在修复范围
 - 实现中遇到方案未覆盖的关键设计决策时，按 `.agents/rules/no-mid-flow-questions.md` 判据，把详情块写入实现报告的 `## 人工裁决待办` 段 `### HD-N：<标题> [needs-human-decision]`（`HD-N` 全局唯一，见 `.agents/rules/review-handshake.md`）并回写 `HD-` 账本行，不中途提问或擅自扩范围
 - 绝不自动执行 `git add` 或 `git commit`
 - 每轮实现都创建新的实现产物，不覆盖旧文件
@@ -168,7 +168,7 @@ date "+%Y-%m-%d %H:%M:%S%:z"
 - 记录 Round `{code-round}` 的 `{code-artifact}`
 - 追加：
   - 初次实现：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N})** by {agent} — Code implemented, {n} files modified, {n} tests passed → {code-artifact}`
-  - 修复模式：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N}, fix for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues[, skipped {n} env-blocked] → {code-artifact}`
+  - 修复模式：`- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Code Task (Round {N}, fix for {review-artifact})** by {agent} — Fixed {n} blockers, {n} major, {n} minor issues[, skipped {n} manual-validation] → {code-artifact}`
 
 如果 task.md 中存在有效的 `issue_number`，执行以下同步操作（任一失败则跳过并继续；执行前先读取 `.agents/rules/issue-sync.md`，完成 upstream 仓库检测和权限检测）：
 - 按 issue-sync.md 设置 `status: in-progress`