@fitlab-ai/agent-infra 0.6.5 → 0.7.0

package/lib/sandbox/commands/ls.ts

@@ -5,51 +5,36 @@ import pc from 'picocolors';
 import { loadConfig } from '../config.ts';
 import { sandboxBranchLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
-import { runSafeEngine } from '../shell.ts';
 import { resolveTools, toolProjectDirCandidates } from '../tools.ts';
+import { fetchSandboxRows } from './list-running.ts';
 
-const USAGE = 'Usage: ai sandbox ls';
-const CONTAINER_TABLE_HEADERS = ['NAMES', 'STATUS', 'BRANCH'] as const;
+export { containerListFormat, parseLabels } from './list-running.ts';
+
+const USAGE = `Usage: ai sandbox ls
+
+Lists all containers for the current project. The leftmost '#' column
+numbers running sandboxes; use it as "ai sandbox exec '#N'" to enter one.
+Quote '#N' to avoid shell '#' comment handling.`;
+
+const CONTAINER_TABLE_HEADERS = ['#', 'NAMES', 'STATUS', 'BRANCH'] as const;
 
 type ContainerTableRow = {
+  index: string;
   name: string;
   status: string;
   branch: string;
 };
 
-// Exported to lock the docker/podman-compatible format in unit tests.
-export function containerListFormat(): string {
-  return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
-}
-
-export function parseLabels(csv: string): Record<string, string> {
-  if (!csv) {
-    return {};
-  }
-
-  const labels: Record<string, string> = {};
-  for (const pair of csv.split(',')) {
-    if (!pair) {
-      continue;
-    }
-    const eq = pair.indexOf('=');
-    if (eq < 0) {
-      continue;
-    }
-    labels[pair.slice(0, eq)] = pair.slice(eq + 1);
-  }
-  return labels;
-}
-
 export function formatContainerTable(rows: ContainerTableRow[]): string[] {
-  const columns = rows.map((row) => [row.name, row.status, row.branch] as const);
+  const columns = rows.map((row) => [row.index, row.name, row.status, row.branch] as const);
   const widths = [
-    Math.max(CONTAINER_TABLE_HEADERS[0].length, ...rows.map((row) => row.name.length)),
-    Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.status.length)),
-    Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.branch.length))
+    Math.max(CONTAINER_TABLE_HEADERS[0].length, ...rows.map((row) => row.index.length)),
+    Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.name.length)),
+    Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.status.length)),
+    Math.max(CONTAINER_TABLE_HEADERS[3].length, ...rows.map((row) => row.branch.length))
   ] as const;
-  const renderRow = (values: readonly [string, string, string]): string =>
-    `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2]}`.trimEnd();
+  const renderRow = (values: readonly [string, string, string, string]): string =>
+    `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2].padEnd(widths[2])}  ${values[3]}`.trimEnd();
 
   return [
     renderRow(CONTAINER_TABLE_HEADERS),
@@ -75,28 +60,22 @@ export function ls(args: string[] = []): void {
   const engine = detectEngine(config);
   const tools = resolveTools(config);
   const label = sandboxLabel(config);
-  const containers = runSafeEngine(engine, 'docker', [
-    'ps',
-    '-a',
-    '--filter',
-    `label=${label}`,
-    '--format',
-    containerListFormat()
-  ]);
+  const { running, nonRunning } = fetchSandboxRows(engine, label, sandboxBranchLabel(config));
 
   p.intro(pc.cyan(`Sandbox status for ${config.project}`));
 
   p.log.step('Containers');
-  if (!containers) {
+  const ordered = [...running, ...nonRunning];
+  if (ordered.length === 0) {
     p.log.warn('  No sandbox containers');
   } else {
-    const branchKey = sandboxBranchLabel(config);
-    const rows = containers.split('\n').map((line) => {
-      const [name = '', status = '', labelsCsv = ''] = line.split('\t');
-      const branch = parseLabels(labelsCsv)[branchKey] ?? '';
-      return { name, status, branch };
-    });
-    for (const line of formatContainerTable(rows)) {
+    const tableRows: ContainerTableRow[] = ordered.map((row) => ({
+      index: row.index === null ? '' : String(row.index),
+      name: row.name,
+      status: row.status,
+      branch: row.branch
+    }));
+    for (const line of formatContainerTable(tableRows)) {
       process.stdout.write(`  ${line}\n`);
     }
   }

package/lib/sandbox/commands/rebuild.ts

@@ -8,7 +8,12 @@ import { prepareDockerfile } from '../dockerfile.ts';
 import { sandboxImageConfigLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine, ensureDocker } from '../engine.ts';
 import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
-import { resolveTools, toolNpmPackagesArg } from '../tools.ts';
+import {
+  imageSignatureFields,
+  resolveTools,
+  toolNpmPackagesArg,
+  toolShellInstallScriptBase64
+} from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
 import { toEnginePath } from '../engines/wsl2-paths.ts';
 import { resolveBuildUid } from '../engines/native.ts';
@@ -23,7 +28,7 @@ function buildSignature(preparedDockerfile: PreparedDockerfile, tools: SandboxTo
   return createHash('sha256')
     .update(JSON.stringify({
       dockerfile: preparedDockerfile.signature,
-      tools: tools.map((tool) => tool.npmPackage)
+      tools: imageSignatureFields(tools)
     }))
     .digest('hex')
     .slice(0, 12);
@@ -66,6 +71,8 @@ export function buildArgs(
     `HOST_GID=${hostGid}`,
     '--build-arg',
     `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+    '--build-arg',
+    `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
     '--label',
     sandboxLabel(config),
     '--label',

package/lib/sandbox/config.ts

@@ -6,6 +6,8 @@ import pc from 'picocolors';
 import { validateSandboxEngine } from './engine.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 import { findRuntimeEngineMismatches } from './runtime-engines.ts';
+import { parseCustomTools } from './tools.ts';
+import type { SandboxTool } from './tools.ts';
 
 const DEFAULTS = Object.freeze({
   engine: null,
@@ -26,6 +28,7 @@ type SandboxConfigInput = {
   engine?: string | null;
   runtimes?: string[];
   tools?: string[];
+  customTools?: unknown;
   dockerfile?: string | null;
   vm?: Record<string, unknown>;
 };
@@ -51,6 +54,7 @@ export type SandboxConfig = {
   engine: string | null;
   runtimes: string[];
   tools: string[];
+  customTools: SandboxTool[];
   dockerfile: string | null;
   vm: SandboxVmConfig;
 };
@@ -136,6 +140,8 @@ export function loadConfig({
     }
   }
 
+  const customTools = parseCustomTools(sandbox.customTools, { home });
+
   return {
     repoRoot,
     configPath,
@@ -153,6 +159,7 @@ export function loadConfig({
     tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
       ? [...sandbox.tools]
       : defaults.tools,
+    customTools,
     dockerfile,
     vm: {
       cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,

package/lib/sandbox/index.ts

@@ -2,7 +2,8 @@ const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
-  exec <branch> [cmd...]       Enter sandbox or run a command
+  exec <branch | '#N'> [cmd...]
+                               Enter sandbox or run a command (use leftmost '#' column from 'ls')
   ls                           List sandboxes for the current project
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]

package/lib/sandbox/runtimes/ai-tools.dockerfile

@@ -4,16 +4,20 @@ ENV OPENCODE_DISABLE_AUTOUPDATE=1
 ENV NPM_CONFIG_PREFIX=/home/devuser/.npm-global
 ENV PATH="/home/devuser/.npm-global/bin:${PATH}"
 
-ARG AI_TOOL_PACKAGES
-RUN if [ -z "${AI_TOOL_PACKAGES}" ]; then \
-      echo "AI_TOOL_PACKAGES build arg is required"; \
-      exit 1; \
-    fi && \
-    set -e && \
+ARG AI_TOOL_PACKAGES=
+RUN set -e && \
     for pkg in ${AI_TOOL_PACKAGES}; do \
       npm install -g "$pkg"; \
     done
 
+ARG AI_TOOLS_SHELL_INSTALL_B64=
+RUN if [ -n "${AI_TOOLS_SHELL_INSTALL_B64}" ]; then \
+      set -e && \
+      echo "${AI_TOOLS_SHELL_INSTALL_B64}" | base64 -d > /tmp/ai-tools-install.sh && \
+      bash /tmp/ai-tools-install.sh && \
+      rm /tmp/ai-tools-install.sh; \
+    fi
+
 RUN npm install -g pyright
 
 RUN mkdir -p /home/devuser/.local/share /home/devuser/.local/state

package/lib/sandbox/tools.ts

@@ -1,10 +1,14 @@
 import { safeNameCandidates, sanitizeBranchName } from './constants.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 
+export type SandboxToolInstall =
+  | { type: 'npm'; cmd: string }
+  | { type: 'shell'; cmd: string };
+
 export type SandboxTool = {
   id: string;
   name: string;
-  npmPackage: string;
+  install: SandboxToolInstall;
   sandboxBase: string;
   containerMount: string;
   versionCmd: string;
@@ -21,14 +25,17 @@ type ToolsConfig = {
   home: string;
   project: string;
   tools: string[];
+  customTools?: SandboxTool[];
 };
 
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
 function createBuiltinTools(home: string, project: string): Record<string, SandboxTool> {
   return {
     'claude-code': {
       id: 'claude-code',
       name: 'Claude Code',
-      npmPackage: '@anthropic-ai/claude-code@stable',
+      install: { type: 'npm', cmd: '@anthropic-ai/claude-code@stable' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
       containerMount: '/home/devuser/.claude',
       versionCmd: 'claude --version',
@@ -58,7 +65,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     codex: {
       id: 'codex',
       name: 'Codex',
-      npmPackage: '@openai/codex',
+      install: { type: 'npm', cmd: '@openai/codex' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
       containerMount: '/home/devuser/.codex',
       versionCmd: 'codex --version',
@@ -73,7 +80,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     opencode: {
       id: 'opencode',
       name: 'OpenCode',
-      npmPackage: 'opencode-ai',
+      install: { type: 'npm', cmd: 'opencode-ai' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
       containerMount: '/home/devuser/.local/share/opencode',
       versionCmd: 'opencode version',
@@ -92,7 +99,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     'gemini-cli': {
       id: 'gemini-cli',
       name: 'Gemini CLI',
-      npmPackage: '@google/gemini-cli',
+      install: { type: 'npm', cmd: '@google/gemini-cli' },
       sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
       containerMount: '/home/devuser/.gemini',
       versionCmd: 'gemini --version',
@@ -108,16 +115,224 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
   };
 }
 
+export function builtinToolIds(): string[] {
+  return Object.keys(createBuiltinTools('', ''));
+}
+
 function validateTool(tool: SandboxTool): void {
-  if (!tool.npmPackage || !tool.containerMount.startsWith('/')) {
-    throw new Error(`Invalid sandbox tool descriptor: ${tool.id}`);
+  if (!tool.id || !TOOL_ID_PATTERN.test(tool.id)) {
+    throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
+  }
+  if (!tool.install || (tool.install.type !== 'npm' && tool.install.type !== 'shell')) {
+    throw new Error(`Sandbox tool ${tool.id} has invalid install.type`);
+  }
+  if (!tool.install.cmd) {
+    throw new Error(`Sandbox tool ${tool.id} has empty install.cmd`);
+  }
+  if (!tool.containerMount || !tool.containerMount.startsWith('/')) {
+    throw new Error(`Sandbox tool ${tool.id} containerMount must be an absolute path`);
+  }
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asString(value: unknown, field: string, context: string): string {
+  if (typeof value !== 'string') {
+    throw new Error(`${context}: field "${field}" must be a string`);
+  }
+  return value;
+}
+
+function asOptionalNonEmptyString(value: unknown, field: string, context: string): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== 'string') {
+    throw new Error(`${context}: field "${field}" must be a string when provided`);
+  }
+  if (value.length === 0) {
+    throw new Error(`${context}: field "${field}" must be non-empty when provided`);
+  }
+  return value;
+}
+
+function asStringRecord(value: unknown, field: string, context: string): Record<string, string> | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!isPlainObject(value)) {
+    throw new Error(`${context}: field "${field}" must be an object when provided`);
+  }
+  const out: Record<string, string> = {};
+  for (const [key, val] of Object.entries(value)) {
+    if (typeof val !== 'string') {
+      throw new Error(`${context}: field "${field}.${key}" must be a string`);
+    }
+    out[key] = val;
+  }
+  return out;
+}
+
+function asStringArray(value: unknown, field: string, context: string): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "${field}" must be an array when provided`);
+  }
+  return value.map((item, index) => {
+    if (typeof item !== 'string') {
+      throw new Error(`${context}: field "${field}[${index}]" must be a string`);
+    }
+    return item;
+  });
+}
+
+function parseInstall(value: unknown, context: string): SandboxToolInstall {
+  if (!isPlainObject(value)) {
+    throw new Error(`${context}: field "install" must be an object`);
+  }
+  const type = value.type;
+  if (type !== 'npm' && type !== 'shell') {
+    throw new Error(`${context}: field "install.type" must be "npm" or "shell"`);
+  }
+  const cmd = asString(value.cmd, 'install.cmd', context);
+  if (!cmd) {
+    throw new Error(`${context}: field "install.cmd" must be non-empty`);
+  }
+  return { type, cmd };
+}
+
+function parseHostPreSeedFiles(value: unknown, context: string): SandboxTool['hostPreSeedFiles'] {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "hostPreSeedFiles" must be an array when provided`);
+  }
+  return value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new Error(`${context}: field "hostPreSeedFiles[${index}]" must be an object`);
+    }
+    return {
+      hostPath: asString(item.hostPath, `hostPreSeedFiles[${index}].hostPath`, context),
+      sandboxName: asString(item.sandboxName, `hostPreSeedFiles[${index}].sandboxName`, context)
+    };
+  });
+}
+
+function parseHostPreSeedDirs(value: unknown, context: string): SandboxTool['hostPreSeedDirs'] {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "hostPreSeedDirs" must be an array when provided`);
   }
+  return value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new Error(`${context}: field "hostPreSeedDirs[${index}]" must be an object`);
+    }
+    return {
+      hostDir: asString(item.hostDir, `hostPreSeedDirs[${index}].hostDir`, context),
+      sandboxSubdir: asString(item.sandboxSubdir, `hostPreSeedDirs[${index}].sandboxSubdir`, context)
+    };
+  });
+}
+
+function parseHostLiveMounts(value: unknown, context: string): SandboxTool['hostLiveMounts'] {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`${context}: field "hostLiveMounts" must be an array when provided`);
+  }
+  return value.map((item, index) => {
+    if (!isPlainObject(item)) {
+      throw new Error(`${context}: field "hostLiveMounts[${index}]" must be an object`);
+    }
+    return {
+      hostPath: asString(item.hostPath, `hostLiveMounts[${index}].hostPath`, context),
+      containerSubpath: asString(item.containerSubpath, `hostLiveMounts[${index}].containerSubpath`, context)
+    };
+  });
+}
+
+export function parseCustomTool(
+  entry: unknown,
+  index: number,
+  options: { home: string }
+): SandboxTool {
+  const context = `customTools[${index}]`;
+  if (!isPlainObject(entry)) {
+    throw new Error(`${context} must be an object`);
+  }
+
+  const id = asString(entry.id, 'id', context);
+  if (!TOOL_ID_PATTERN.test(id)) {
+    throw new Error(`${context}: field "id" must match ${TOOL_ID_PATTERN.source}`);
+  }
+
+  const containerMount = asOptionalNonEmptyString(entry.containerMount, 'containerMount', context)
+    ?? `/home/devuser/.${id}`;
+  if (!containerMount.startsWith('/')) {
+    throw new Error(`${context}: field "containerMount" must be an absolute path`);
+  }
+
+  const tool: SandboxTool = {
+    id,
+    name: asOptionalNonEmptyString(entry.name, 'name', context) ?? id,
+    install: parseInstall(entry.install, context),
+    sandboxBase: hostJoin(options.home, '.agent-infra', 'sandboxes', id),
+    containerMount,
+    versionCmd: asOptionalNonEmptyString(entry.versionCmd, 'versionCmd', context) ?? `which ${id}`,
+    setupHint: asOptionalNonEmptyString(entry.setupHint, 'setupHint', context)
+      ?? `Run \`${id}\` inside the container to set up.`,
+    envVars: asStringRecord(entry.envVars, 'envVars', context),
+    hostPreSeedFiles: parseHostPreSeedFiles(entry.hostPreSeedFiles, context),
+    hostPreSeedDirs: parseHostPreSeedDirs(entry.hostPreSeedDirs, context),
+    pathRewriteFiles: asStringArray(entry.pathRewriteFiles, 'pathRewriteFiles', context),
+    hostLiveMounts: parseHostLiveMounts(entry.hostLiveMounts, context),
+    postSetupCmds: asStringArray(entry.postSetupCmds, 'postSetupCmds', context)
+  };
+
+  validateTool(tool);
+  return tool;
+}
+
+export function parseCustomTools(value: unknown, options: { home: string }): SandboxTool[] {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  if (!Array.isArray(value)) {
+    throw new Error('sandbox: "customTools" must be an array');
+  }
+  return value.map((entry, index) => parseCustomTool(entry, index, options));
 }
 
 export function resolveTools(config: ToolsConfig): SandboxTool[] {
   const builtins = createBuiltinTools(config.home, config.project);
+  const customs = config.customTools ?? [];
+
+  const seen = new Set<string>();
+  for (const tool of customs) {
+    if (builtins[tool.id]) {
+      throw new Error(`Custom sandbox tool id "${tool.id}" collides with a built-in tool`);
+    }
+    if (seen.has(tool.id)) {
+      throw new Error(`Duplicate sandbox tool id "${tool.id}" in customTools`);
+    }
+    seen.add(tool.id);
+  }
+
+  const merged: Record<string, SandboxTool> = { ...builtins };
+  for (const tool of customs) {
+    merged[tool.id] = tool;
+  }
+
   return config.tools.map((id) => {
-    const tool = builtins[id];
+    const tool = merged[id];
     if (!tool) {
       throw new Error(`Unknown sandbox tool: ${id}`);
     }
@@ -139,5 +354,29 @@ export function toolProjectDirCandidates(tool: SandboxTool, project: string): st
 }
 
 export function toolNpmPackagesArg(tools: SandboxTool[]): string {
-  return tools.map((tool) => tool.npmPackage).join(' ');
+  return tools
+    .filter((tool) => tool.install.type === 'npm')
+    .map((tool) => tool.install.cmd)
+    .join(' ');
+}
+
+export function toolShellInstallScript(tools: SandboxTool[]): string {
+  const blocks = tools
+    .filter((tool) => tool.install.type === 'shell')
+    .map((tool) => `# install: ${tool.id}\n${tool.install.cmd}`);
+
+  if (blocks.length === 0) {
+    return '';
+  }
+
+  return ['#!/bin/bash', 'set -e', '', ...blocks, ''].join('\n');
+}
+
+export function toolShellInstallScriptBase64(tools: SandboxTool[]): string {
+  const script = toolShellInstallScript(tools);
+  return script ? Buffer.from(script, 'utf8').toString('base64') : '';
+}
+
+export function imageSignatureFields(tools: SandboxTool[]): Array<{ id: string; install: SandboxToolInstall }> {
+  return tools.map((tool) => ({ id: tool.id, install: tool.install }));
 }

package/lib/update.ts

@@ -15,6 +15,7 @@ type UpdateConfig = {
   org: string;
   language: string;
   platform?: { type?: string };
+  requiresPullRequest?: boolean;
   sandbox?: Record<string, unknown>;
   labels?: Record<string, unknown>;
   files?: Partial<FileRegistry>;
@@ -22,6 +23,7 @@ type UpdateConfig = {
 
 type Defaults = {
   platform: { type: string };
+  requiresPullRequest: boolean;
   sandbox: Record<string, unknown>;
   labels: Record<string, unknown>;
   files: FileRegistry;
@@ -178,6 +180,7 @@ async function cmdUpdate(): Promise<void> {
   const platformAdded = !config.platform;
   const sandboxAdded = !config.sandbox;
   const labelsAdded = !config.labels;
+  const requiresPullRequestAdded = config.requiresPullRequest === undefined;
   let configChanged = changed;
 
   if (platformAdded) {
@@ -195,6 +198,11 @@ async function cmdUpdate(): Promise<void> {
     configChanged = true;
   }
 
+  if (requiresPullRequestAdded) {
+    config.requiresPullRequest = defaults.requiresPullRequest;
+    configChanged = true;
+  }
+
   if (configChanged) {
     console.log('');
     if (hasNewEntries) {
@@ -205,7 +213,7 @@ async function cmdUpdate(): Promise<void> {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (platformAdded || sandboxAdded || labelsAdded) {
+    } else if (platformAdded || sandboxAdded || labelsAdded || requiresPullRequestAdded) {
       if (platformAdded) {
         info(`Default platform config added to ${CONFIG_PATH}.`);
       }
@@ -215,6 +223,9 @@ 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}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
@@ -227,6 +238,9 @@ 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}.`);
+    }
     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.6.5",
+  "version": "0.7.0",
   "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/QUICKSTART.en.md

@@ -164,7 +164,7 @@ The receiving AI should read this document first to get up to speed.
 
 ### 1. One AI Per Phase
 
-Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analyze, design, implement, review, fix, commit.
+Don't have multiple AIs working on the same files simultaneously. Follow the sequential workflow: analysis → analysis-review → design → design-review → code → code-review → commit (when any review finds issues, re-run the matching upstream stage).
 
 ### 2. Always Create Handoff Documents
 

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

@@ -164,7 +164,7 @@ cp .agents/templates/handoff.md .agents/workspace/active/handoff-task-001-phase2
 
 ### 1. 每个阶段一个 AI
 
-不要让多个 AI 同时处理相同的文件。遵循顺序工作流：分析、设计、实现、审查、修复、提交。
+不要让多个 AI 同时处理相同的文件。遵循顺序工作流：分析 → 分析审查 → 设计 → 设计审查 → 编码 → 代码审查 → 提交（任一审查发现问题时，回到同名上游阶段重跑）。
 
 ### 2. 始终创建交接文档