@fitlab-ai/agent-infra 0.5.6 → 0.5.7

package/README.md

@@ -314,6 +314,7 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 |-------|-------------|------------|----------------------|
 | `release` | Execute the version release workflow. | `version` (`X.Y.Z`) | Publish a new project release. |
 | `create-release-note` | Generate release notes from PRs and commits. | `version`, `previous-version` (optional) | Prepare a changelog before shipping. |
+| `post-release` | Run post-release follow-up tasks (version bump, artifact rebuild, optional demo capture). | None | Finalize the release cycle after pushing a release tag. |
 
 <a id="security-skills"></a>
 
@@ -392,7 +393,7 @@ If you maintain reusable team skills outside the repository, declare them in `.a
 {
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" },
+      { "type": "local", "path": "~/private-skills" },
       { "type": "local", "path": "~/team-skills" }
     ]
   }
@@ -402,7 +403,7 @@ If you maintain reusable team skills outside the repository, declare them in `.a
 Expected source layout:
 
 ```text
-~/company-skills/
+~/private-skills/
   enforce-style/
     SKILL.md
   release-check/
@@ -427,6 +428,54 @@ When `update-agent-infra` runs:
 - Built-in skills always win over custom sources; if a source defines a skill with the same name as a built-in skill, agent-infra skips that custom source skill instead of overriding the built-in one
 - If you truly need to replace a built-in skill or command, use the existing `ejected` mechanism and own that file in the project
 
+## Custom TUI Configuration
+
+Use the top-level `.agents/.airc.json` `customTUIs` array when your team uses an AI TUI that is not one of the built-in command targets. This config lets agent-infra show the correct next-step commands and generate command files for project custom skills by learning from an existing command in the custom TUI directory.
+
+| Field | Required | Meaning |
+|-------|----------|---------|
+| `name` | Yes | Display name shown in reports and next-step guidance, for example `Acme TUI`. |
+| `dir` | Yes | Command directory relative to the project root, for example `.acme/commands`. The path must stay inside the project root. |
+| `invoke` | Yes | User-facing command template used in next-step guidance. |
+
+Supported `invoke` placeholders:
+
+| Placeholder | Replaced with | Example |
+|-------------|---------------|---------|
+| `${skillName}` | The skill command name, such as `review-task` or `commit`. | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+Non-namespaced custom TUI:
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+Namespaced custom TUI:
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` should contain one entry per custom TUI. To let `update-agent-infra` generate command files for custom skills, keep at least one existing command file in `dir` that references a built-in skill path such as `.agents/skills/analyze-task/SKILL.md`; agent-infra uses that file as the format reference.
+
 <a id="prebuilt-workflows"></a>
 
 ## Prebuilt Workflows
@@ -496,12 +545,24 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.6",
+  "templateVersion": "v0.5.7",
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" }
+      { "type": "local", "path": "~/private-skills" }
     ]
   },
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ],
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -530,10 +591,37 @@ The generated `.agents/.airc.json` file is the central contract between the boot
 | `org` | GitHub organization or owner used by generated metadata and links. |
 | `language` | Primary project language or locale used by rendered templates. |
 | `templateVersion` | Installed template version for future upgrades and drift tracking. |
+| `templates` | Optional external template overlay configuration. |
+| `templates.sources` | Optional ordered list of external template sources. Only `type: "local"` is supported today. |
 | `skills` | Optional custom skill sync configuration. |
 | `skills.sources` | Optional ordered list of external custom skill sources. Only `type: "local"` is supported today. |
+| `customTUIs` | Optional top-level list of custom AI TUI adapters. |
 | `files` | Per-path update strategy configuration for managed, merged, and ejected files. |
 
+### External template and skill sources
+
+Use external sources when your team maintains private platform templates, private rules, or shared custom skills outside this repository. You can configure them during `agent-infra init` or later by editing `.agents/.airc.json`:
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" },
+      { "type": "local", "path": "~/team-overrides/templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+Template source precedence is built-in templates first, then external sources as supplements. External files with the same path as built-in templates are ignored and reported in `templateSources.conflicts`; between external sources, later entries override earlier entries and conflicts are also reported. Skill sources use the same local-source shape, but custom skills cannot replace built-in skills.
+
+External template files and skill scripts can include executable JavaScript or shell commands that AI workflows may run. Only use trusted local paths.
+
 <a id="file-management-strategies"></a>
 
 ## File Management Strategies

package/README.zh-CN.md

@@ -314,6 +314,7 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 |-------|------|------|---------|
 | `release` | 执行版本发布流程。 | `version`（`X.Y.Z`） | 发布新版本时。 |
 | `create-release-note` | 基于 PR 和 commit 生成发布说明。 | `version`、`previous-version`（可选） | 发布前准备 changelog 时。 |
+| `post-release` | 执行版本发布后的收尾工作（版本 bump、产物重建、可选动图录制）。 | 无 | 推送发布标签后完成收尾。 |
 
 <a id="security-skills"></a>
 
@@ -392,7 +393,7 @@ args: "<task-id>"   # 可选
 {
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" },
+      { "type": "local", "path": "~/private-skills" },
       { "type": "local", "path": "~/team-skills" }
     ]
   }
@@ -402,7 +403,7 @@ args: "<task-id>"   # 可选
 源目录结构示例：
 
 ```text
-~/company-skills/
+~/private-skills/
   enforce-style/
     SKILL.md
   release-check/
@@ -427,6 +428,54 @@ args: "<task-id>"   # 可选
 - 内置 skill 始终优先于自定义 source；如果 source 里出现与内置 skill 同名的目录，agent-infra 会跳过该 source skill，而不是覆盖内置实现
 - 如果你确实需要替换内置 skill 或命令，请使用现有的 `ejected` 机制，让项目自己接管该文件
 
+## 自定义 TUI 配置
+
+当团队使用的 AI TUI 不属于内置命令目标时，可以在 `.agents/.airc.json` 顶层配置 `customTUIs` 数组。该配置用于让 agent-infra 输出正确的下一步命令，并通过学习自定义 TUI 目录中的既有命令文件，为项目自定义 skill 生成同格式命令。
+
+| 字段 | 必填 | 含义 |
+|------|------|------|
+| `name` | 是 | 报告和下一步提示中展示的工具名称，例如 `Acme TUI`。 |
+| `dir` | 是 | 相对项目根目录的命令目录，例如 `.acme/commands`。路径必须位于项目根目录内。 |
+| `invoke` | 是 | 面向用户展示的命令模板，用于生成下一步提示。 |
+
+`invoke` 支持的占位符：
+
+| 占位符 | 替换为 | 示例 |
+|--------|--------|------|
+| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `acme ${skillName}` -> `acme review-task` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+
+不带命名空间的自定义 TUI：
+
+```json
+{
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ]
+}
+```
+
+带命名空间的自定义 TUI：
+
+```json
+{
+  "project": "agent-infra",
+  "customTUIs": [
+    {
+      "name": "Internal Gemini",
+      "dir": ".internal-gemini/commands",
+      "invoke": "/${projectName}:${skillName}"
+    }
+  ]
+}
+```
+
+`customTUIs` 每个条目对应一个自定义 TUI。若希望 `update-agent-infra` 为自定义 skill 生成命令文件，请在 `dir` 中保留至少一个引用内置 skill 路径的既有命令文件，例如 `.agents/skills/analyze-task/SKILL.md`；agent-infra 会以该文件作为格式参考。
+
 <a id="prebuilt-workflows"></a>
 
 ## 预置工作流
@@ -496,12 +545,24 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.5.6",
+  "templateVersion": "v0.5.7",
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" }
+    ]
+  },
   "skills": {
     "sources": [
-      { "type": "local", "path": "~/company-skills" }
+      { "type": "local", "path": "~/private-skills" }
     ]
   },
+  "customTUIs": [
+    {
+      "name": "Acme TUI",
+      "dir": ".acme/commands",
+      "invoke": "acme ${skillName}"
+    }
+  ],
   "files": {
     "managed": [
       ".agents/workspace/README.md",
@@ -530,10 +591,37 @@ import-issue #42                    从 GitHub Issue 导入任务
 | `org` | 生成元数据和链接时使用的 GitHub 组织或拥有者。 |
 | `language` | 渲染模板时采用的项目主语言或区域设置。 |
 | `templateVersion` | 当前安装的模板版本，用于升级和差异追踪。 |
+| `templates` | 可选的外部模板叠加配置。 |
+| `templates.sources` | 可选的外部模板源列表，按顺序应用。当前仅支持 `type: "local"`。 |
 | `skills` | 可选的自定义 skill 同步配置。 |
 | `skills.sources` | 可选的外部自定义 skill 源列表，按顺序应用。当前仅支持 `type: "local"`。 |
+| `customTUIs` | 可选的顶层自定义 AI TUI 适配配置列表。 |
 | `files` | 针对具体路径配置 `managed`、`merged`、`ejected` 三类更新策略。 |
 
+### 外部模板与 skill 源
+
+当团队在仓库外维护私有平台模板、私有规则或共享自定义 skill 时，可以使用外部源。你可以在 `agent-infra init` 时配置，也可以之后手动编辑 `.agents/.airc.json`：
+
+```json
+{
+  "templates": {
+    "sources": [
+      { "type": "local", "path": "~/private-templates" },
+      { "type": "local", "path": "~/team-overrides/templates" }
+    ]
+  },
+  "skills": {
+    "sources": [
+      { "type": "local", "path": "~/private-skills" }
+    ]
+  }
+}
+```
+
+模板源优先级是内置模板优先，外部源作为补充。外部源中与内置模板同路径的文件会被忽略，并记录到 `templateSources.conflicts`；多个外部源之间，后面的条目覆盖前面的条目，冲突同样会记录。Skill 源使用相同的本地源结构，但自定义 skill 不能替换内置 skill。
+
+外部模板文件和 skill 脚本可能包含 AI 工作流会执行的 JavaScript 或 shell 命令。只使用可信的本地路径。
+
 <a id="file-management-strategies"></a>
 
 ## 文件管理策略

package/bin/cli.js

@@ -35,9 +35,27 @@ Examples:
 
 const command = process.argv[2] || '';
 
+async function importCommand(importPath) {
+  try {
+    return await import(importPath);
+  } catch (error) {
+    if (error?.code === 'ERR_MODULE_NOT_FOUND') {
+      process.stderr.write(
+        'Error: Missing npm dependency. Run npm install before using agent-infra from a development checkout.\n'
+      );
+      process.stderr.write(`${error.message}\n`);
+      process.exitCode = 1;
+      return null;
+    }
+    throw error;
+  }
+}
+
 switch (command) {
   case 'init': {
-    const { cmdInit } = await import('../lib/init.js');
+    const imported = await importCommand('../lib/init.js');
+    if (!imported) break;
+    const { cmdInit } = imported;
     await cmdInit().catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;
@@ -45,7 +63,9 @@ switch (command) {
     break;
   }
   case 'update': {
-    const { cmdUpdate } = await import('../lib/update.js');
+    const imported = await importCommand('../lib/update.js');
+    if (!imported) break;
+    const { cmdUpdate } = imported;
     await cmdUpdate().catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;
@@ -53,7 +73,9 @@ switch (command) {
     break;
   }
   case 'merge': {
-    const { cmdMerge } = await import('../lib/merge.js');
+    const imported = await importCommand('../lib/merge.js');
+    if (!imported) break;
+    const { cmdMerge } = imported;
     await cmdMerge(process.argv.slice(3)).catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;
@@ -61,7 +83,9 @@ switch (command) {
     break;
   }
   case 'sandbox': {
-    const { runSandbox } = await import('../lib/sandbox/index.js');
+    const imported = await importCommand('../lib/sandbox/index.js');
+    if (!imported) break;
+    const { runSandbox } = imported;
     await runSandbox(process.argv.slice(3)).catch((e) => {
       process.stderr.write(`Error: ${e.message}\n`);
       process.exitCode = 1;

package/lib/defaults.json

@@ -3,6 +3,7 @@
     "type": "github"
   },
   "sandbox": {
+    "engine": null,
     "runtimes": [
       "node20"
     ],

package/lib/init.js

@@ -1,10 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
 import { info, ok, err } from './log.js';
-import { prompt, closePrompt } from './prompt.js';
+import { prompt, select, closePrompt } from './prompt.js';
 import { resolveTemplateDir } from './paths.js';
-import { renderFile, copySkillDir } from './render.js';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
 import { VERSION } from './version.js';
 
 const defaults = JSON.parse(
@@ -39,10 +40,19 @@ function detectOrgName() {
 
 const VALID_NAME_RE = /^[a-zA-Z0-9_.@-]+$/;
 
+function parseLocalSources(input) {
+  return input
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => ({ type: 'local', path: entry }));
+}
+
 async function cmdInit() {
   console.log('');
   console.log('  agent-infra init');
   console.log('  ================================');
+  console.log('  Optional template and skill sources can be added now or later in .agents/.airc.json.');
   console.log('');
 
   // resolve templates
@@ -100,14 +110,52 @@ async function cmdInit() {
     return;
   }
 
-  const platformType = (await prompt('Platform type', 'github')).trim() || 'github';
-  closePrompt();
+  let sandboxEngine = null;
+  if (platform() === 'darwin') {
+    sandboxEngine = await select(
+      'Sandbox engine (macOS)',
+      ['colima', 'orbstack', 'docker-desktop'],
+      'colima'
+    );
+  }
+
+  const platformChoices = [...KNOWN_PLATFORMS, 'other'];
+  let platformType = await select('Platform', platformChoices, 'github');
+
+  if (platformType === 'other') {
+    platformType = (await prompt('Custom platform type', '')).trim();
+    if (!platformType) {
+      closePrompt();
+      err('Custom platform type is required.');
+      process.exitCode = 1;
+      return;
+    }
+  }
+
   if (!/^[a-z0-9][a-z0-9-]*$/.test(platformType)) {
+    closePrompt();
     err(`Platform type must match /^[a-z0-9][a-z0-9-]*$/. Got: ${platformType}`);
     process.exitCode = 1;
     return;
   }
 
+  if (!KNOWN_PLATFORMS.has(platformType)) {
+    info(
+      `Custom platform '${platformType}' selected. Built-in templates are only complete for github;`
+      + ` provide matching '.${platformType}.' or generic templates before running update-agent-infra.`
+    );
+  }
+
+  const templateSources = parseLocalSources(await prompt(
+    'Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)',
+    ''
+  ));
+  const skillSources = parseLocalSources(await prompt(
+    'Skill sources (optional, comma-separated local paths, e.g. ~/my-skills; Enter to skip)',
+    ''
+  ));
+  closePrompt();
+
   const project = projectName;
   const replacements = { project, org: orgName };
 
@@ -177,6 +225,22 @@ async function cmdInit() {
     files: structuredClone(defaults.files)
   };
 
+  if (sandboxEngine) {
+    config.sandbox.engine = sandboxEngine;
+  }
+
+  if (templateSources.length > 0) {
+    config.templates = {
+      sources: templateSources
+    };
+  }
+
+  if (skillSources.length > 0) {
+    config.skills = {
+      sources: skillSources
+    };
+  }
+
   fs.mkdirSync(path.dirname(configPath), { recursive: true });
   fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
   ok(`Generated ${configPath}`);

package/lib/prompt.js

@@ -59,6 +59,33 @@ async function prompt(question, defaultValue) {
   return line.trim() || defaultValue || '';
 }
 
+async function select(question, choices, defaultValue) {
+  const defaultIndex = choices.indexOf(defaultValue);
+
+  process.stdout.write(`  ${question}:\n`);
+  choices.forEach((choice, index) => {
+    const suffix = index === defaultIndex ? ' (default)' : '';
+    process.stdout.write(`      ${index + 1}) ${choice}${suffix}\n`);
+  });
+
+  ask(defaultIndex >= 0 ? `Select [${defaultIndex + 1}]: ` : 'Select: ');
+
+  setupInterface();
+
+  const line = await nextLine();
+  if (line === null || line.trim() === '') {
+    return defaultValue || choices[0];
+  }
+
+  const trimmed = line.trim();
+  const selectedIndex = Number.parseInt(trimmed, 10);
+  if (String(selectedIndex) === trimmed && selectedIndex >= 1 && selectedIndex <= choices.length) {
+    return choices[selectedIndex - 1];
+  }
+
+  return trimmed;
+}
+
 function closePrompt() {
   if (_rl) {
     _rl.close();
@@ -67,4 +94,4 @@ function closePrompt() {
   }
 }
 
-export { prompt, closePrompt };
+export { prompt, select, closePrompt };

package/lib/render.js

@@ -158,4 +158,4 @@ function copySkillDir(srcDir, dstDir, replacements, language, platform = 'github
   }
 }
 
-export { renderFile, copyFile, copySkillDir };
+export { renderFile, copyFile, copySkillDir, KNOWN_PLATFORMS };

package/lib/sandbox/commands/rm.js

@@ -11,7 +11,7 @@ import {
   sandboxLabel,
   worktreeDirCandidates
 } from '../constants.js';
-import { isVmManaged } from '../engine.js';
+import { detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.js';
 import { run, runOk, runSafe } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
 import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.js';
@@ -165,13 +165,15 @@ async function rmAll(config, tools) {
     runSafe('docker', ['rmi', config.imageName]);
   }
 
-  if (isVmManaged()) {
+  const engine = detectEngine(config);
+  if (isManagedEngine(engine)) {
+    const name = engineDisplayName(engine);
     const shouldStopVm = await p.confirm({
-      message: 'Stop Colima VM?',
+      message: `Stop ${name} VM?`,
       initialValue: false
     });
     if (!p.isCancel(shouldStopVm) && shouldStopVm) {
-      runSafe('colima', ['stop']);
+      stopManagedVm(config);
     }
   }
 

package/lib/sandbox/commands/vm.js

@@ -3,31 +3,49 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.js';
 import { parsePositiveIntegerOption } from '../constants.js';
-import { detectEngine, ensureDocker, isVmManaged } from '../engine.js';
-import { run, runOk, runSafe } from '../shell.js';
+import {
+  ENGINES,
+  detectEngine,
+  engineDisplayName,
+  ensureDocker,
+  isManagedEngine,
+  stopManagedVm
+} from '../engine.js';
+import { runOk, runSafe } from '../shell.js';
 
 const USAGE = `Usage: ai sandbox vm <status|start|stop> [--cpu <n>] [--memory <n>]`;
 
-function ensureManagedVm() {
-  if (!isVmManaged()) {
-    throw new Error(`VM management is unavailable on ${detectEngine()}.`);
+function ensureManagedVm(engine) {
+  if (!isManagedEngine(engine)) {
+    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
   }
 }
 
 function status() {
-  ensureManagedVm();
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const name = engineDisplayName(engine);
+  ensureManagedVm(engine);
   p.intro(pc.cyan('Sandbox VM status'));
 
-  if (runOk('colima', ['status'])) {
-    process.stdout.write(`${runSafe('colima', ['status'])}\n`);
-  } else {
-    p.log.warn('Colima VM is not running');
+  if (engine === ENGINES.COLIMA) {
+    if (runOk('colima', ['status'])) {
+      process.stdout.write(`${runSafe('colima', ['status'])}\n`);
+    } else {
+      p.log.warn('Colima VM is not running');
+    }
+    return;
+  }
+
+  if (!runOk('orb', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
+    return;
   }
+
+  process.stdout.write(`${runSafe('orb', ['status'])}\n`);
 }
 
 async function start(args) {
-  ensureManagedVm();
-
   const { values } = parseArgs({
     args,
     allowPositionals: true,
@@ -45,6 +63,8 @@ async function start(args) {
   }
 
   const config = loadConfig();
+  const engine = detectEngine(config);
+  ensureManagedVm(engine);
   const effectiveConfig = {
     ...config,
     vm: {
@@ -62,15 +82,22 @@ async function start(args) {
 }
 
 function stop() {
-  ensureManagedVm();
+  const config = loadConfig();
+  const engine = detectEngine(config);
+  const name = engineDisplayName(engine);
+  ensureManagedVm(engine);
   p.intro(pc.cyan('Stopping sandbox VM'));
 
-  if (!runOk('colima', ['status'])) {
-    p.log.warn('Colima VM is not running');
+  if (engine === ENGINES.COLIMA && !runOk('colima', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
+    return;
+  }
+  if (engine === ENGINES.ORBSTACK && !runOk('orb', ['status'])) {
+    p.log.warn(`${name} VM is not running`);
     return;
   }
 
-  run('colima', ['stop']);
+  stopManagedVm(config);
   p.outro(pc.green('VM stopped'));
 }
 

package/lib/sandbox/config.js

@@ -1,8 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { validateSandboxEngine } from './engine.js';
 
 const DEFAULTS = Object.freeze({
+  engine: null,
   runtimes: ['node20'],
   tools: ['claude-code', 'codex', 'opencode', 'gemini-cli'],
   dockerfile: null,
@@ -26,6 +28,7 @@ function detectRepoRoot() {
 
 function cloneDefaults() {
   return {
+    engine: DEFAULTS.engine,
     runtimes: [...DEFAULTS.runtimes],
     tools: [...DEFAULTS.tools],
     dockerfile: DEFAULTS.dockerfile,
@@ -49,6 +52,7 @@ export function loadConfig() {
   const airc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
+  const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine);
   const project = airc.project;
 
   if (!project || typeof project !== 'string') {
@@ -64,6 +68,7 @@ export function loadConfig() {
     containerPrefix: `${project}-dev`,
     imageName: `${project}-sandbox:latest`,
     worktreeBase: path.join(home, '.agent-infra', 'worktrees', project),
+    engine,
     runtimes: Array.isArray(sandbox.runtimes) && sandbox.runtimes.length > 0
       ? [...sandbox.runtimes]
       : defaults.runtimes,