@fitlab-ai/agent-infra 0.4.5 → 0.5.0

package/lib/sandbox/dockerfile.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+const RUNTIMES_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  'runtimes'
+);
+
+function listRuntimeFragments() {
+  return fs.readdirSync(RUNTIMES_DIR)
+    .filter((file) => file.endsWith('.dockerfile'))
+    .map((file) => file.replace(/\.dockerfile$/, ''));
+}
+
+export function availableRuntimes() {
+  return listRuntimeFragments()
+    .filter((name) => name !== 'base' && name !== 'ai-tools')
+    .sort();
+}
+
+function dockerfileContent(config) {
+  if (config.dockerfile) {
+    const customPath = path.resolve(config.repoRoot, config.dockerfile);
+    if (!fs.existsSync(customPath)) {
+      throw new Error(`Custom Dockerfile not found: ${customPath}`);
+    }
+    return fs.readFileSync(customPath, 'utf8');
+  }
+
+  const validRuntimes = new Set(availableRuntimes());
+  for (const runtime of config.runtimes) {
+    if (!validRuntimes.has(runtime)) {
+      throw new Error(
+        `Unknown runtime: ${runtime}. Available runtimes: ${[...validRuntimes].join(', ')}`
+      );
+    }
+  }
+
+  const fragments = [
+    'base.dockerfile',
+    ...config.runtimes.map((runtime) => `${runtime}.dockerfile`),
+    'ai-tools.dockerfile'
+  ];
+
+  const content = fragments
+    .map((fragment) => fs.readFileSync(path.join(RUNTIMES_DIR, fragment), 'utf8').trimEnd())
+    .join('\n\n');
+
+  return `${content}\n`;
+}
+
+export function dockerfileSignature(config) {
+  return createHash('sha256')
+    .update(dockerfileContent(config))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+export function prepareDockerfile(config) {
+  if (config.dockerfile) {
+    const customPath = path.resolve(config.repoRoot, config.dockerfile);
+    if (!fs.existsSync(customPath)) {
+      throw new Error(`Custom Dockerfile not found: ${customPath}`);
+    }
+
+    return {
+      path: customPath,
+      signature: dockerfileSignature(config),
+      cleanup() {}
+    };
+  }
+
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `${config.project}-sandbox-`));
+  const tempPath = path.join(tempDir, 'Dockerfile');
+  fs.writeFileSync(tempPath, dockerfileContent(config), 'utf8');
+
+  return {
+    path: tempPath,
+    signature: dockerfileSignature(config),
+    cleanup() {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+  };
+}
+
+export function composeDockerfile(config) {
+  const content = dockerfileContent(config);
+
+  const tempPath = path.join(os.tmpdir(), `${config.project}-sandbox.Dockerfile`);
+  fs.writeFileSync(tempPath, content, 'utf8');
+  return tempPath;
+}

package/lib/sandbox/engine.js

@@ -0,0 +1,93 @@
+import { platform } from 'node:os';
+import { detectHostResources } from './constants.js';
+import { run, runOk, runSafe, runVerbose } from './shell.js';
+
+export function detectEngine() {
+  const os = platform();
+  if (os === 'darwin') {
+    return 'colima';
+  }
+  if (os === 'linux') {
+    return 'native';
+  }
+  if (os === 'win32') {
+    return 'wsl2';
+  }
+  return 'unsupported';
+}
+
+function colimaArgs(config, runSafeFn = runSafe) {
+  const arch = runSafeFn('uname', ['-m']);
+  const defaults = detectHostResources();
+  const cpu = config.vm.cpu ?? defaults.cpu;
+  const memory = config.vm.memory ?? defaults.memory;
+  const disk = config.vm.disk ?? 60;
+  const args = ['start', '--cpu', String(cpu), '--memory', String(memory), '--disk', String(disk)];
+
+  if (arch === 'arm64') {
+    args.push('--arch', 'aarch64', '--vm-type=vz', '--mount-type=virtiofs');
+  } else {
+    args.push('--arch', 'x86_64');
+  }
+
+  return args;
+}
+
+export async function ensureColima(
+  config,
+  onMessage,
+  { runOkFn = runOk, runSafeFn = runSafe, runVerboseFn = runVerbose } = {}
+) {
+  if (!runOkFn('which', ['colima'])) {
+    onMessage?.('Installing colima + docker via Homebrew...');
+    runVerboseFn('brew', ['install', 'colima', 'docker']);
+  }
+
+  if (!runOkFn('colima', ['status'])) {
+    onMessage?.('Starting Colima VM...');
+    runVerboseFn('colima', colimaArgs(config, runSafeFn));
+  }
+
+  if (!runOkFn('docker', ['info'])) {
+    throw new Error('Docker daemon is not available after starting Colima');
+  }
+}
+
+export async function ensureDocker(config, onMessage) {
+  const engine = detectEngine();
+
+  if (engine === 'colima') {
+    await ensureColima(config, onMessage);
+    return;
+  }
+
+  if (engine === 'native') {
+    if (!runOk('docker', ['info'])) {
+      throw new Error('Docker daemon is not running. Please start Docker first.');
+    }
+    return;
+  }
+
+  if (engine === 'wsl2') {
+    throw new Error('Windows sandbox support is reserved for a future WSL2 implementation.');
+  }
+
+  throw new Error(`Unsupported sandbox engine: ${engine}`);
+}
+
+export function isVmManaged() {
+  return detectEngine() === 'colima';
+}
+
+export function startManagedVm(config) {
+  if (!isVmManaged()) {
+    throw new Error('VM management is only available on macOS with Colima.');
+  }
+
+  if (runOk('colima', ['status'])) {
+    return 'already-running';
+  }
+
+  runVerbose('colima', colimaArgs(config));
+  return 'started';
+}

package/lib/sandbox/index.js

@@ -0,0 +1,64 @@
+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
+  ls                           List sandboxes for the current project
+  rm <branch> [--all]          Remove a sandbox or all sandboxes
+  vm status|start|stop         Manage the sandbox VM (macOS only)
+  rebuild [--quiet]            Rebuild the sandbox image
+
+Run 'ai sandbox <command> --help' for details.`;
+
+export async function runSandbox(args) {
+  const [subcommand, ...rest] = args;
+
+  if (!subcommand) {
+    process.stdout.write(`${USAGE}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+    process.stdout.write(`${USAGE}\n`);
+    return;
+  }
+
+  switch (subcommand) {
+    case 'create': {
+      const { create } = await import('./commands/create.js');
+      await create(rest);
+      break;
+    }
+    case 'exec': {
+      const { enter } = await import('./commands/enter.js');
+      const exitCode = enter(rest);
+      if (typeof exitCode === 'number' && exitCode !== 0) {
+        process.exitCode = exitCode;
+      }
+      break;
+    }
+    case 'ls': {
+      const { ls } = await import('./commands/ls.js');
+      ls(rest);
+      break;
+    }
+    case 'rm': {
+      const { rm } = await import('./commands/rm.js');
+      await rm(rest);
+      break;
+    }
+    case 'vm': {
+      const { vm } = await import('./commands/vm.js');
+      await vm(rest);
+      break;
+    }
+    case 'rebuild': {
+      const { rebuild } = await import('./commands/rebuild.js');
+      await rebuild(rest);
+      break;
+    }
+    default:
+      throw new Error(`Unknown sandbox command: ${subcommand}`);
+  }
+}

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

@@ -0,0 +1,26 @@
+USER devuser
+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 && \
+    npm install -g ${AI_TOOL_PACKAGES}
+
+RUN npm install -g pyright
+
+RUN mkdir -p /home/devuser/.local/share /home/devuser/.local/state
+
+RUN git config --global --add safe.directory /workspace
+
+RUN echo 'export NPM_CONFIG_PREFIX=/home/devuser/.npm-global' >> /home/devuser/.bashrc && \
+    echo 'export PATH="/home/devuser/.npm-global/bin:${PATH}"' >> /home/devuser/.bashrc && \
+    echo 'export GIT_CONFIG_GLOBAL=/home/devuser/.gitconfig' >> /home/devuser/.bashrc && \
+    echo 'export GPG_TTY=$(tty)' >> /home/devuser/.bashrc && \
+    echo '[ -f ~/.bash_aliases ] && . ~/.bash_aliases' >> /home/devuser/.bashrc
+
+WORKDIR /workspace
+
+CMD ["tail", "-f", "/dev/null"]

package/lib/sandbox/runtimes/base.dockerfile

@@ -0,0 +1,30 @@
+FROM ubuntu:22.04
+
+LABEL description="AI coding sandbox"
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV TZ=Asia/Shanghai
+
+ARG HOST_UID=1000
+ARG HOST_GID=1000
+RUN (groupadd -g ${HOST_GID} devuser || true) && \
+    useradd -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser
+
+RUN apt-get update && apt-get install -y \
+    curl wget git vim file \
+    build-essential ca-certificates gnupg lsb-release \
+    locales \
+    && locale-gen en_US.UTF-8 \
+    && (curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
+        | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg) \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
+        > /etc/apt/sources.list.d/github-cli.list \
+    && apt-get update && apt-get install -y gh \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV LANG=en_US.UTF-8
+ENV LC_ALL=en_US.UTF-8
+ENV TERM=xterm-256color
+ENV COLORTERM=truecolor
+
+RUN ln -s /workspace /home/devuser/workspace

package/lib/sandbox/runtimes/java17.dockerfile

@@ -0,0 +1,3 @@
+RUN apt-get update && apt-get install -y \
+    openjdk-17-jdk maven \
+    && rm -rf /var/lib/apt/lists/*

package/lib/sandbox/runtimes/java21.dockerfile

@@ -0,0 +1,3 @@
+RUN apt-get update && apt-get install -y \
+    openjdk-21-jdk maven \
+    && rm -rf /var/lib/apt/lists/*

package/lib/sandbox/runtimes/node20.dockerfile

@@ -0,0 +1,3 @@
+RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
+    apt-get install -y nodejs && \
+    rm -rf /var/lib/apt/lists/*

package/lib/sandbox/runtimes/node22.dockerfile

@@ -0,0 +1,3 @@
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - && \
+    apt-get install -y nodejs && \
+    rm -rf /var/lib/apt/lists/*

package/lib/sandbox/runtimes/python3.dockerfile

@@ -0,0 +1,3 @@
+RUN apt-get update && apt-get install -y \
+    python3 python3-pip python3-venv \
+    && rm -rf /var/lib/apt/lists/*

package/lib/sandbox/shell.js

@@ -0,0 +1,48 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
+
+function normalizeOptions(opts = {}, stdio) {
+  return {
+    cwd: opts.cwd,
+    encoding: opts.encoding,
+    stdio,
+    timeout: opts.timeout ?? DEFAULT_TIMEOUT_MS
+  };
+}
+
+export function run(cmd, args, opts = {}) {
+  return execFileSync(cmd, args, {
+    ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
+    encoding: 'utf8'
+  }).trim();
+}
+
+export function runOk(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, normalizeOptions(opts, 'pipe'));
+  return result.status === 0;
+}
+
+export function runInteractive(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, normalizeOptions(opts, 'inherit'));
+  return result.status ?? 1;
+}
+
+export function runVerbose(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, normalizeOptions(opts, 'inherit'));
+
+  if (result.status !== 0) {
+    if (result.signal === 'SIGTERM') {
+      throw new Error(`Command timed out after ${opts.timeout ?? DEFAULT_TIMEOUT_MS}ms: ${cmd} ${args.join(' ')}`);
+    }
+    throw new Error(`Command failed with exit code ${result.status}: ${cmd} ${args.join(' ')}`);
+  }
+}
+
+export function runSafe(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, {
+    ...normalizeOptions(opts, ['pipe', 'pipe', 'pipe']),
+    encoding: 'utf8',
+  });
+  return (result.stdout ?? '').trim();
+}

package/lib/sandbox/task-resolver.js

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+
+function readTaskContent(repoRoot, taskId) {
+  const taskPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+  if (!fs.existsSync(taskPath)) {
+    throw new Error(`Task not found: ${taskId}`);
+  }
+  return fs.readFileSync(taskPath, 'utf8');
+}
+
+function resolveBranchFromTaskContent(content, taskId) {
+  const frontmatterBranch = content.match(/^branch:\s*(.+)$/m);
+  if (frontmatterBranch && frontmatterBranch[1].trim()) {
+    return frontmatterBranch[1].trim();
+  }
+
+  const contextBranch = content.match(/^- \*\*(?:分支|Branch)\*\*：[ \t]*`?([^`\n]+)`?$/m);
+  if (contextBranch && contextBranch[1].trim()) {
+    return contextBranch[1].trim();
+  }
+
+  throw new Error(`Task ${taskId} has no branch field in task.md`);
+}
+
+export function resolveTaskBranch(arg, repoRoot) {
+  if (!TASK_ID_RE.test(arg)) {
+    return arg;
+  }
+
+  const content = readTaskContent(repoRoot, arg);
+  return resolveBranchFromTaskContent(content, arg);
+}

package/lib/sandbox/tools.js

@@ -0,0 +1,131 @@
+import path from 'node:path';
+import { safeNameCandidates, sanitizeBranchName } from './constants.js';
+
+/**
+ * @typedef {Object} SandboxTool
+ * @property {string} id
+ * @property {string} name
+ * @property {string} npmPackage
+ * @property {string} sandboxBase
+ * @property {string} containerMount
+ * @property {string} versionCmd
+ * @property {string} setupHint
+ * @property {Record<string, string>=} envVars
+ * @property {Array<{ hostPath: string, sandboxName: string }>=} hostPreSeedFiles
+ * @property {Array<{ hostDir: string, sandboxSubdir: string }>=} hostPreSeedDirs
+ * @property {string[]=} pathRewriteFiles
+ * @property {Array<{ hostPath: string, containerSubpath: string }>=} hostLiveMounts
+ * @property {string[]=} postSetupCmds
+ */
+
+function createBuiltinTools(home, project) {
+  /** @type {Record<string, SandboxTool>} */
+  return {
+    'claude-code': {
+      id: 'claude-code',
+      name: 'Claude Code',
+      npmPackage: '@anthropic-ai/claude-code',
+      sandboxBase: path.join(home, '.claude-sandboxes'),
+      containerMount: '/home/devuser/.claude',
+      versionCmd: 'claude --version',
+      setupHint: 'Authenticates via host credentials live-mounted at ~/.claude/.credentials.json',
+      // Claude Code stores user data (.claude.json — onboarding state, theme,
+      // workspace trust) at $HOME/.claude.json by default, which sits OUTSIDE
+      // the bind-mounted /home/devuser/.claude tree, so our preseeded
+      // .claude.json never gets read and the theme picker re-runs on every
+      // container start. Pinning CLAUDE_CONFIG_DIR to the tool mount relocates
+      // .claude.json into the same directory as .credentials.json/settings.json,
+      // letting ensureClaudeOnboarding actually take effect.
+      envVars: { CLAUDE_CONFIG_DIR: '/home/devuser/.claude' },
+      hostPreSeedDirs: [
+        { hostDir: path.join(home, '.claude', 'plugins'), sandboxSubdir: 'plugins' }
+      ],
+      pathRewriteFiles: [
+        'plugins/installed_plugins.json',
+        'plugins/known_marketplaces.json'
+      ],
+      hostLiveMounts: [
+        {
+          hostPath: path.join(home, `.${project}-claude-credentials`, '.credentials.json'),
+          containerSubpath: '.credentials.json'
+        }
+      ]
+    },
+    codex: {
+      id: 'codex',
+      name: 'Codex',
+      npmPackage: '@openai/codex',
+      sandboxBase: path.join(home, '.codex-sandboxes'),
+      containerMount: '/home/devuser/.codex',
+      versionCmd: 'codex --version',
+      setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
+      hostLiveMounts: [
+        { hostPath: path.join(home, '.codex', 'auth.json'), containerSubpath: 'auth.json' }
+      ],
+      postSetupCmds: [
+        'test -d /workspace/.codex/commands && ln -sfn /workspace/.codex/commands /home/devuser/.codex/prompts || true'
+      ]
+    },
+    opencode: {
+      id: 'opencode',
+      name: 'OpenCode',
+      npmPackage: 'opencode-ai',
+      sandboxBase: path.join(home, '.opencode-sandboxes'),
+      containerMount: '/home/devuser/.local/share/opencode',
+      versionCmd: 'opencode version',
+      setupHint: 'Configure OpenCode credentials inside the container before first use.',
+      hostLiveMounts: [
+        {
+          hostPath: path.join(home, '.local', 'share', 'opencode', 'auth.json'),
+          containerSubpath: 'auth.json'
+        }
+      ]
+    },
+    'gemini-cli': {
+      id: 'gemini-cli',
+      name: 'Gemini CLI',
+      npmPackage: '@google/gemini-cli',
+      sandboxBase: path.join(home, '.gemini-sandboxes'),
+      containerMount: '/home/devuser/.gemini',
+      versionCmd: 'gemini --version',
+      setupHint: 'Run gemini inside the container to finish authentication.',
+      hostLiveMounts: [
+        { hostPath: path.join(home, '.gemini', 'oauth_creds.json'), containerSubpath: 'oauth_creds.json' }
+      ],
+      hostPreSeedFiles: [
+        { hostPath: path.join(home, '.gemini', 'settings.json'), sandboxName: 'settings.json' },
+        { hostPath: path.join(home, '.gemini', 'google_accounts.json'), sandboxName: 'google_accounts.json' }
+      ]
+    }
+  };
+}
+
+function validateTool(tool) {
+  if (!tool.npmPackage || !tool.containerMount.startsWith('/')) {
+    throw new Error(`Invalid sandbox tool descriptor: ${tool.id}`);
+  }
+}
+
+export function resolveTools(config) {
+  const builtins = createBuiltinTools(config.home, config.project);
+  return config.tools.map((id) => {
+    const tool = builtins[id];
+    if (!tool) {
+      throw new Error(`Unknown sandbox tool: ${id}`);
+    }
+    validateTool(tool);
+    return tool;
+  });
+}
+
+export function toolConfigDir(tool, project, branch) {
+  return path.join(tool.sandboxBase, project, sanitizeBranchName(branch));
+}
+
+export function toolConfigDirCandidates(tool, project, branch) {
+  return safeNameCandidates(branch).map((name) => path.join(tool.sandboxBase, project, name));
+}
+
+export function toolNpmPackagesArg(tools) {
+  return tools.map((tool) => tool.npmPackage).join(' ');
+}

package/lib/update.js

@@ -139,9 +139,15 @@ async function cmdUpdate() {
   // sync file registry
   const { added, changed } = syncFileRegistry(config);
   const hasNewEntries = added.managed.length > 0 || added.merged.length > 0;
+  const sandboxAdded = !config.sandbox;
   const labelsAdded = !config.labels;
   let configChanged = changed;
 
+  if (sandboxAdded) {
+    config.sandbox = structuredClone(defaults.sandbox);
+    configChanged = true;
+  }
+
   if (labelsAdded) {
     config.labels = structuredClone(defaults.labels);
     configChanged = true;
@@ -157,11 +163,19 @@ async function cmdUpdate() {
       for (const entry of added.merged) {
         ok(`  merged: ${entry}`);
       }
-    } else if (labelsAdded) {
-      info(`Default labels.in config added to ${CONFIG_PATH}.`);
+    } else if (sandboxAdded || labelsAdded) {
+      if (sandboxAdded) {
+        info(`Default sandbox config added to ${CONFIG_PATH}.`);
+      }
+      if (labelsAdded) {
+        info(`Default labels.in config added to ${CONFIG_PATH}.`);
+      }
     } else {
       info(`File registry changed in ${CONFIG_PATH}.`);
     }
+    if (hasNewEntries && sandboxAdded) {
+      info(`Default sandbox config added to ${CONFIG_PATH}.`);
+    }
     if (hasNewEntries && labelsAdded) {
       info(`Default labels.in config added to ${CONFIG_PATH}.`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.4.5",
+  "version": "0.5.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Gemini CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -40,6 +40,10 @@
     "bootstrap",
     "installer"
   ],
+  "dependencies": {
+    "@clack/prompts": "1.2.0",
+    "picocolors": "1.1.1"
+  },
   "scripts": {
     "build": "node scripts/build-inline.js",
     "prepare": "git config core.hooksPath .github/hooks || true",

package/templates/.agents/scripts/validate-artifact.js

@@ -33,6 +33,7 @@ const DEFAULT_RETRY_DELAYS_MS = [3000, 10000];
 const DEFAULT_FRESHNESS_MINUTES = 30;
 const DATE_TIME_PATTERN = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/;
 const ACTIVITY_LOG_PATTERN = /^- (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}) — \*\*(.+?)\*\* by (.+?) — (.+)$/;
+const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 const scriptPath = fileURLToPath(import.meta.url);
 const repoRoot = path.resolve(path.dirname(scriptPath), "..", "..");
@@ -190,6 +191,11 @@ function checkTaskMeta({ taskDir, config }) {
     }
   }
 
+  const branchValidationError = validateTaskBranch(metadata);
+  if (branchValidationError) {
+    return failResult("task-meta", branchValidationError);
+  }
+
   const expectedStep = config.expected_step;
   if (expectedStep && metadata.current_step !== expectedStep) {
     return failResult(
@@ -232,6 +238,40 @@ function checkTaskMeta({ taskDir, config }) {
   return passResult("task-meta", `Task metadata valid (${requiredFields.length} required fields checked)`);
 }
 
+function validateTaskBranch(metadata) {
+  if (isBlank(metadata.branch)) {
+    return null;
+  }
+
+  const projectName = loadProjectName();
+  const expectedPrefix = projectName ? `${projectName}-${metadata.type}-` : "";
+
+  if (expectedPrefix && !String(metadata.branch).startsWith(expectedPrefix)) {
+    return `Invalid branch: expected prefix '${expectedPrefix}', got '${metadata.branch}'`;
+  }
+
+  const slug = expectedPrefix ? String(metadata.branch).slice(expectedPrefix.length) : String(metadata.branch);
+  if (!BRANCH_SLUG_PATTERN.test(slug)) {
+    return `Invalid branch: '${metadata.branch}' must use kebab-case suffixes`;
+  }
+
+  return null;
+}
+
+function loadProjectName() {
+  const configPath = path.join(repoRoot, ".agents", ".airc.json");
+  if (!fs.existsSync(configPath)) {
+    return "";
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+    return String(config.project || "").trim();
+  } catch {
+    return "";
+  }
+}
+
 function checkArtifact({ taskDir, config, artifactFile }) {
   const resolvedArtifact = resolveArtifactPath(taskDir, config.file_pattern, artifactFile);
   if (!resolvedArtifact.ok) {