@fitlab-ai/agent-infra 0.5.8 → 0.5.10

package/lib/sandbox/commands/create.js

@@ -1,10 +1,12 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { parseArgs } from 'node:util';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
+import * as toml from 'smol-toml';
 import { loadConfig } from '../config.js';
 import {
   assertValidBranchName,
@@ -15,13 +17,34 @@ import {
   sandboxImageConfigLabel,
   sandboxLabel,
   sanitizeBranchName,
+  shareBranchDir,
+  shareCommonDir,
   worktreeDirCandidates
 } from '../constants.js';
 import { prepareDockerfile } from '../dockerfile.js';
-import { ensureDocker } from '../engine.js';
-import { run, runOk, runSafe, runVerbose } from '../shell.js';
+import { detectEngine, ensureDocker } from '../engine.js';
+import {
+  commandForEngine,
+  execEngine,
+  run,
+  runEngine,
+  runOk,
+  runOkEngine,
+  runSafe,
+  runSafeEngine,
+  runVerboseEngine
+} from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
 import { resolveTools, toolConfigDirCandidates, toolNpmPackagesArg } from '../tools.js';
+import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
+import { validateSelinuxDisableEnv } from '../engines/selinux.js';
+import { resolveBuildUid } from '../engines/native.js';
+import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
+import {
+  assertClaudeCredentialsAvailable,
+  redactCommandError,
+  validateClaudeCredentialsEnvOverride
+} from '../credentials.js';
 
 const OPENCODE_YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
@@ -47,11 +70,14 @@ alias xy='codex --yolo; tput ed'
 alias gy='gemini --yolo; tput ed'
 `;
 const CONTAINER_HOME = '/home/devuser';
+const CONTAINER_SHELL_CONFIG_MOUNT = `${CONTAINER_HOME}/.host-shell-config`;
 const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>]
 
 Host aliases:
-  ${'~'}/.agent-infra/aliases/sandbox.sh is auto-created on first run and mounted at
-  ${CONTAINER_HOME}/.bash_aliases inside the sandbox container.`;
+  ${'~'}/.agent-infra/aliases/sandbox.sh is auto-created on first run and exposed
+  as ${CONTAINER_HOME}/.bash_aliases inside the sandbox container (the host
+  shell-config directory is bind-mounted at ${CONTAINER_SHELL_CONFIG_MOUNT} and
+  symlinked into $HOME).`;
 
 function buildSignature(preparedDockerfile, tools) {
   return createHash('sha256')
@@ -63,10 +89,6 @@ function buildSignature(preparedDockerfile, tools) {
     .slice(0, 12);
 }
 
-function hostJoin(basePath, ...segments) {
-  return basePath.startsWith('/') ? path.posix.join(basePath, ...segments) : path.join(basePath, ...segments);
-}
-
 function resolveToolDirs(config, tools, branch) {
   return tools.map((tool) => {
     const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -78,7 +100,7 @@ function resolveToolDirs(config, tools, branch) {
 }
 
 export function hostShellConfigDir(home, project, branch) {
-  return path.join(home, '.agent-infra', 'config', project, sanitizeBranchName(branch));
+  return hostJoin(home, '.agent-infra', 'config', project, sanitizeBranchName(branch));
 }
 
 function runtimeChecks(runtimes) {
@@ -162,9 +184,17 @@ function appendSafeDirectories(lines, repoRoot) {
   return updatedLines;
 }
 
+function normalizeContainerHomeSeparators(content) {
+  const containerHomePattern = new RegExp(`${escapeRegExp(CONTAINER_HOME)}\\S*`, 'g');
+  return content.replace(containerHomePattern, (value) => value.replaceAll('\\', '/'));
+}
+
 export function sanitizeGitConfig(gitconfig, home, { stripGpg = false, repoRoot = '' } = {}) {
-  const lines = gitconfig
+  const posixHome = home.replaceAll('\\', '/');
+  const normalizedGitconfig = gitconfig
     .replaceAll(home, CONTAINER_HOME)
+    .replaceAll(posixHome, CONTAINER_HOME);
+  const lines = normalizeContainerHomeSeparators(normalizedGitconfig)
     .replace(/\[difftool "sourcetree"\][^\[]*/gs, '')
     .replace(/\[mergetool "sourcetree"\][^\[]*/gs, '')
     .split(/\r?\n/);
@@ -216,56 +246,65 @@ export function hostHasGpgKeys(home, execFn = execFileSync) {
 }
 
 export function writeSanitizedGitconfig({ home, hostConfigDir, stripGpg, repoRoot }) {
-  const gitconfigPath = path.join(home, '.gitconfig');
-  if (!fs.existsSync(gitconfigPath)) {
-    return null;
-  }
+  const gitconfigPath = hostJoin(home, '.gitconfig');
+  // Always emit a sanitized .gitconfig, even when the host has none. The
+  // container ~/.gitconfig is a symlink into the bound shell-config directory;
+  // a missing file would leave the symlink dangling and drop the default
+  // safe.directory entries the image relies on.
+  const sourceContent = fs.existsSync(gitconfigPath)
+    ? fs.readFileSync(gitconfigPath, 'utf8')
+    : '';
 
   fs.mkdirSync(hostConfigDir, { recursive: true });
   const targetPath = path.join(hostConfigDir, '.gitconfig');
-  const gitconfig = sanitizeGitConfig(fs.readFileSync(gitconfigPath, 'utf8'), home, {
-    stripGpg,
-    repoRoot
-  });
+  const gitconfig = sanitizeGitConfig(sourceContent, home, { stripGpg, repoRoot });
   fs.writeFileSync(targetPath, gitconfig, 'utf8');
   return targetPath;
 }
 
+// Files inside the host shell-config bind that need to be exposed in $HOME.
+// Keep in sync with the symlink block in lib/sandbox/runtimes/ai-tools.dockerfile.
+const SHELL_CONFIG_SYMLINKS = ['.gitconfig', '.gitignore_global', '.stCommitMsg', '.bash_aliases'];
+
+export function ensureShellConfigSymlinks(engine, container, execFn = execEngine) {
+  // Idempotent symlink setup. Runs against a started container so it also
+  // covers custom Dockerfiles that don't bake the symlinks into the image.
+  const script = SHELL_CONFIG_SYMLINKS
+    .map((file) => `ln -sf .host-shell-config/${file} ${CONTAINER_HOME}/${file}`)
+    .join(' && ');
+  execFn(engine, 'docker', ['exec', container, 'bash', '-lc', script], { stdio: 'ignore' });
+}
+
 export function prepareHostShellConfig({ home, project, branch, repoRoot }) {
   const hostDir = hostShellConfigDir(home, project, branch);
   fs.rmSync(hostDir, { recursive: true, force: true });
   fs.mkdirSync(hostDir, { recursive: true });
 
-  /** @type {Array<{ hostPath: string, containerPath: string }>} */
-  const mounts = [];
-  const gitconfigPath = writeSanitizedGitconfig({
+  writeSanitizedGitconfig({
     home,
     hostConfigDir: hostDir,
     stripGpg: true,
     repoRoot
   });
-  if (gitconfigPath) {
-    mounts.push({ hostPath: gitconfigPath, containerPath: `${CONTAINER_HOME}/.gitconfig` });
-  }
 
   for (const file of ['.gitignore_global', '.stCommitMsg']) {
-    const hostPath = path.join(home, file);
+    const hostPath = hostJoin(home, file);
     if (!fs.existsSync(hostPath)) {
       continue;
     }
 
-    const targetPath = path.join(hostDir, file);
-    fs.copyFileSync(hostPath, targetPath);
-    mounts.push({ hostPath: targetPath, containerPath: `${CONTAINER_HOME}/${file}` });
+    fs.copyFileSync(hostPath, path.join(hostDir, file));
   }
 
   const aliasesPath = sandboxAliasesPath(home);
   if (fs.existsSync(aliasesPath)) {
-    const targetPath = path.join(hostDir, '.bash_aliases');
-    fs.copyFileSync(aliasesPath, targetPath);
-    mounts.push({ hostPath: targetPath, containerPath: `${CONTAINER_HOME}/.bash_aliases` });
+    fs.copyFileSync(aliasesPath, path.join(hostDir, '.bash_aliases'));
   }
 
+  // Single directory bind keeps virtiofs happy: per-file rewrites inside no
+  // longer race the bind layer like individual single-file binds do.
+  const mounts = [{ hostPath: hostDir, containerPath: CONTAINER_SHELL_CONFIG_MOUNT }];
+
   return { hostDir, mounts };
 }
 
@@ -410,7 +449,9 @@ export function syncGpgKeys(
   const {
     cachedOverride = null,
     repoPath = null,
-    signingKey: signingKeyOverride
+    signingKey: signingKeyOverride,
+    dockerExecFn = execFn,
+    dockerRunSafeFn = runSafeFn
   } = options;
   const hostEnv = { ...process.env, HOME: home };
   let signingKey = normalizeSigningKey(signingKeyOverride);
@@ -463,28 +504,86 @@ export function syncGpgKeys(
     }
   }
 
-  execFn('docker', ['exec', '-i', container, 'gpg', '--import'], {
+  dockerExecFn('docker', ['exec', '-i', container, 'gpg', '--import'], {
     input: pubKeys,
     stdio: ['pipe', 'pipe', 'pipe']
   });
-  execFn('docker', ['exec', '-i', container, 'gpg', '--batch', '--import'], {
+  dockerExecFn('docker', ['exec', '-i', container, 'gpg', '--batch', '--import'], {
     input: secKeys,
     stdio: ['pipe', 'pipe', 'pipe']
   });
 
-  runSafeFn('docker', ['exec', container, 'gpgconf', '--launch', 'gpg-agent']);
+  dockerRunSafeFn('docker', ['exec', container, 'gpgconf', '--launch', 'gpg-agent']);
   return true;
 }
 
-export function buildContainerEnvArgs(resolvedTools, runSafeCommand = runSafe) {
-  const envArgs = resolvedTools.flatMap(({ tool }) =>
-    Object.entries(tool.envVars ?? {}).flatMap(([key, value]) => ['-e', `${key}=${value}`])
-  );
-  const ghToken = runSafeCommand('gh', ['auth', 'token']);
+// Docker `--env-file` parsing has no quoting/escaping support and treats
+// leading '#' as a comment. Newlines split entries, so reject them outright.
+// Other shell metacharacters are safe because the values are not expanded.
+function formatEnvFileEntry(key, value) {
+  if (String(key).includes('\n') || String(value).includes('\n')) {
+    throw new Error(`Container environment variable ${key} must not contain newlines`);
+  }
+  return `${key}=${value}`;
+}
+
+export function buildContainerEnvFile(
+  resolvedTools,
+  engine,
+  runSafeEngineFn = runSafeEngine,
+  options = {}
+) {
+  const {
+    mkdtempFn = fs.mkdtempSync,
+    writeFileFn = fs.writeFileSync,
+    chmodFn = fs.chmodSync,
+    rmFn = fs.rmSync,
+    tmpDir = os.tmpdir()
+  } = options;
+
+  const entries = resolvedTools.flatMap(({ tool }) => Object.entries(tool.envVars ?? {}));
+  const ghToken = runSafeEngineFn(engine, 'gh', ['auth', 'token']);
   if (ghToken) {
-    envArgs.push('-e', `GH_TOKEN=${ghToken}`);
+    entries.push(['GH_TOKEN', ghToken]);
+  }
+
+  if (entries.length === 0) {
+    return { dockerArgs: [], cleanup: () => {} };
+  }
+
+  const dir = mkdtempFn(path.join(tmpDir, 'agent-infra-env-'));
+  try {
+    chmodFn(dir, 0o700);
+    const envPath = path.join(dir, 'env');
+    const content = `${entries.map(([key, value]) => formatEnvFileEntry(key, value)).join('\n')}\n`;
+    writeFileFn(envPath, content, { mode: 0o600 });
+    chmodFn(envPath, 0o600);
+
+    return {
+      dockerArgs: ['--env-file', toEnginePath(engine, envPath)],
+      cleanup: () => {
+        try {
+          rmFn(dir, { recursive: true, force: true });
+        } catch {
+          // Best-effort cleanup only.
+        }
+      }
+    };
+  } catch (error) {
+    try {
+      rmFn(dir, { recursive: true, force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+    throw error;
+  }
+}
+
+export function buildDotfilesVolumeArgs(engine, snapshotDir, existsFn = fs.existsSync) {
+  if (!snapshotDir || !existsFn(snapshotDir)) {
+    return [];
   }
-  return envArgs;
+  return ['-v', volumeArg(engine, snapshotDir, '/dotfiles', ':ro')];
 }
 
 export function assertBranchAvailable(
@@ -521,7 +620,20 @@ export function assertBranchAvailable(
   }
 }
 
-export function ensureClaudeOnboarding(toolDir) {
+function readHostJsonSafe(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function ensureClaudeOnboarding(toolDir, hostHomeDir) {
   const claudeJsonPath = path.join(toolDir, '.claude.json');
   let data = {};
   if (fs.existsSync(claudeJsonPath)) {
@@ -548,12 +660,44 @@ export function ensureClaudeOnboarding(toolDir) {
     data.projects['/workspace'].hasTrustDialogAccepted = true;
     changed = true;
   }
+  if (hostHomeDir) {
+    const hostClaudeJson = readHostJsonSafe(path.join(hostHomeDir, '.claude.json'));
+    if (
+      hostClaudeJson
+      && typeof hostClaudeJson.model === 'string'
+      && hostClaudeJson.model !== ''
+      && !Object.hasOwn(data, 'model')
+    ) {
+      data.model = hostClaudeJson.model;
+      changed = true;
+    }
+    // Claude Code launch-pins a default effort per model generation (for
+    // example xhigh for Opus 4.7). The saved effortLevel is honored only after
+    // a top-level boolean `unpin*LaunchEffort: true` flag unlocks it, so mirror
+    // those flags here with the existing first-write semantics.
+    //
+    // Pattern matching avoids one patch per future model generation. If
+    // Anthropic changes the naming convention, this block will no-op and should
+    // be revisited.
+    if (hostClaudeJson) {
+      for (const key of Object.keys(hostClaudeJson)) {
+        if (
+          /^unpin.*LaunchEffort$/.test(key)
+          && hostClaudeJson[key] === true
+          && !Object.hasOwn(data, key)
+        ) {
+          data[key] = true;
+          changed = true;
+        }
+      }
+    }
+  }
   if (changed) {
     fs.writeFileSync(claudeJsonPath, JSON.stringify(data, null, 4), 'utf8');
   }
 }
 
-export function ensureClaudeSettings(toolDir) {
+export function ensureClaudeSettings(toolDir, hostHomeDir) {
   const settingsPath = path.join(toolDir, 'settings.json');
   let data = {};
   if (fs.existsSync(settingsPath)) {
@@ -563,12 +707,74 @@ export function ensureClaudeSettings(toolDir) {
       // malformed JSON, start fresh
     }
   }
+  let changed = false;
   if (data.skipDangerousModePermissionPrompt !== true) {
     data.skipDangerousModePermissionPrompt = true;
+    changed = true;
+  }
+  if (hostHomeDir) {
+    const hostSettings = readHostJsonSafe(path.join(hostHomeDir, '.claude', 'settings.json'));
+    if (
+      hostSettings
+      && typeof hostSettings.effortLevel === 'string'
+      && hostSettings.effortLevel !== ''
+      && !Object.hasOwn(data, 'effortLevel')
+    ) {
+      data.effortLevel = hostSettings.effortLevel;
+      changed = true;
+    }
+  }
+  if (changed) {
     fs.writeFileSync(settingsPath, JSON.stringify(data, null, 4), 'utf8');
   }
 }
 
+export function ensureCodexModelInheritance(toolDir, hostHomeDir) {
+  if (!hostHomeDir) {
+    return;
+  }
+
+  const hostConfigPath = path.join(hostHomeDir, '.codex', 'config.toml');
+  if (!fs.existsSync(hostConfigPath)) {
+    return;
+  }
+
+  let hostParsed;
+  try {
+    hostParsed = toml.parse(fs.readFileSync(hostConfigPath, 'utf8'));
+  } catch {
+    return;
+  }
+
+  const sandboxConfigPath = path.join(toolDir, 'config.toml');
+  // This rewrites sandbox-side TOML and drops comments; the host config stays untouched.
+  let sandboxParsed = {};
+  if (fs.existsSync(sandboxConfigPath)) {
+    try {
+      sandboxParsed = toml.parse(fs.readFileSync(sandboxConfigPath, 'utf8'));
+    } catch {
+      return;
+    }
+  }
+
+  let changed = false;
+  for (const key of ['model', 'model_reasoning_effort']) {
+    if (Object.hasOwn(sandboxParsed, key)) {
+      continue;
+    }
+    const value = hostParsed[key];
+    if (typeof value !== 'string' || value === '') {
+      continue;
+    }
+    sandboxParsed[key] = value;
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(sandboxConfigPath, `${toml.stringify(sandboxParsed)}\n`, 'utf8');
+  }
+}
+
 export function ensureCodexWorkspaceTrust(toolDir) {
   const configPath = path.join(toolDir, 'config.toml');
   let content = '';
@@ -581,6 +787,44 @@ export function ensureCodexWorkspaceTrust(toolDir) {
   }
 }
 
+export function ensureOpenCodeModelInheritance(toolDir, hostHomeDir) {
+  if (!hostHomeDir) {
+    return;
+  }
+
+  const hostConfigPath = path.join(hostHomeDir, '.config', 'opencode', 'opencode.json');
+  const hostJson = readHostJsonSafe(hostConfigPath);
+  if (!hostJson) {
+    return;
+  }
+
+  const sandboxConfigPath = path.join(toolDir, 'opencode.json');
+  let sandboxJson = {};
+  if (fs.existsSync(sandboxConfigPath)) {
+    const existing = readHostJsonSafe(sandboxConfigPath);
+    if (!existing) {
+      return;
+    }
+    sandboxJson = existing;
+  }
+  let changed = false;
+  for (const key of ['model', 'small_model']) {
+    if (Object.hasOwn(sandboxJson, key)) {
+      continue;
+    }
+    const value = hostJson[key];
+    if (typeof value !== 'string' || value === '') {
+      continue;
+    }
+    sandboxJson[key] = value;
+    changed = true;
+  }
+
+  if (changed) {
+    fs.writeFileSync(sandboxConfigPath, JSON.stringify(sandboxJson, null, 2), 'utf8');
+  }
+}
+
 export function ensureGeminiWorkspaceTrust(toolDir) {
   const trustPath = path.join(toolDir, 'trustedFolders.json');
   let data = {};
@@ -597,113 +841,8 @@ export function ensureGeminiWorkspaceTrust(toolDir) {
   }
 }
 
-export function extractClaudeCredentialsBlob(home, execFn = execFileSync) {
-  if (process.platform === 'darwin') {
-    try {
-      const keychainAccount = path.basename(home);
-      const credentials = execFn('security', [
-        'find-generic-password',
-        '-a',
-        keychainAccount,
-        '-s',
-        'Claude Code-credentials',
-        '-w'
-      ], {
-        encoding: 'utf8',
-        stdio: ['ignore', 'pipe', 'pipe']
-      });
-      const trimmed = typeof credentials === 'string' ? credentials.trim() : '';
-      if (!trimmed) {
-        return null;
-      }
-
-      const parsed = JSON.parse(trimmed);
-      const payload = parsed?.claudeAiOauth ?? parsed;
-      const scopes = Array.isArray(payload?.scopes) ? payload.scopes : [];
-      const hasRequiredScopes = scopes.includes('user:profile')
-        && scopes.includes('user:sessions:claude_code');
-      if (!payload?.accessToken || !payload?.refreshToken || !hasRequiredScopes) {
-        return null;
-      }
-      return trimmed;
-    } catch {
-      return null;
-    }
-  }
-
-  const credentialsPath = path.join(home, '.claude', '.credentials.json');
-  if (!fs.existsSync(credentialsPath)) {
-    return null;
-  }
-
-  try {
-    const raw = fs.readFileSync(credentialsPath, 'utf8');
-    const parsed = JSON.parse(raw);
-    const payload = parsed?.claudeAiOauth ?? parsed;
-    const scopes = Array.isArray(payload?.scopes) ? payload.scopes : [];
-    const hasRequiredScopes = scopes.includes('user:profile')
-      && scopes.includes('user:sessions:claude_code');
-    if (!payload?.accessToken || !payload?.refreshToken || !hasRequiredScopes) {
-      return null;
-    }
-    return raw;
-  } catch {
-    return null;
-  }
-}
-
-export function claudeCredentialsDir(home, project) {
-  return hostJoin(home, '.agent-infra', 'credentials', project, 'claude-code');
-}
-
-export function claudeCredentialsPath(home, project) {
-  return hostJoin(claudeCredentialsDir(home, project), '.credentials.json');
-}
-
-export function writeClaudeCredentialsFile(home, project, blob) {
-  const dir = claudeCredentialsDir(home, project);
-  const filePath = claudeCredentialsPath(home, project);
-
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  fs.chmodSync(dir, 0o700);
-  fs.writeFileSync(filePath, blob, { mode: 0o600 });
-  fs.chmodSync(filePath, 0o600);
-}
-
-export function assertClaudeCredentialsAvailable(
-  home,
-  project,
-  resolvedTools,
-  extractFn = extractClaudeCredentialsBlob,
-  writeFn = writeClaudeCredentialsFile
-) {
-  const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
-  if (!claudeCodeEntry) {
-    return;
-  }
-
-  const blob = extractFn(home);
-  if (!blob) {
-    throw new Error([
-      'Claude Code credentials not found on host.',
-      '',
-      'The sandbox needs your Claude Code OAuth credentials so the container can use Claude Code.',
-      '',
-      'To fix:',
-      '  1. On the host, run "claude" once and complete the OAuth login flow.',
-      '  2. Verify with "claude /status" that you see your subscription.',
-      '  3. Re-run "ai sandbox create".',
-      '',
-      'Alternatively, if you do not need Claude Code in this sandbox,',
-      'remove "claude-code" from the "sandbox.tools" array in .agents/.airc.json.'
-    ].join('\n'));
-  }
-
-  writeFn(home, project, blob);
-}
-
 export function sandboxAliasesPath(home) {
-  return path.join(home, '.agent-infra', 'aliases', 'sandbox.sh');
+  return hostJoin(home, '.agent-infra', 'aliases', 'sandbox.sh');
 }
 
 function escapeRegExp(value) {
@@ -759,7 +898,7 @@ export function ensureSandboxAliasesFile(home) {
 
 export function commandErrorMessage(error) {
   const stderr = error?.stderr?.toString().trim();
-  return stderr || error?.message || 'Command failed';
+  return redactCommandError(stderr || error?.message || 'Command failed');
 }
 
 function runTaskCommand(cmd, args, opts = {}) {
@@ -770,17 +909,32 @@ function runTaskCommand(cmd, args, opts = {}) {
   }
 }
 
+function runEngineTaskCommand(engine, cmd, args, opts = {}) {
+  const command = commandForEngine(engine, cmd, args);
+  return runTaskCommand(command.cmd, command.args, opts);
+}
+
 export function buildImage(
   config,
   tools,
   dockerfilePath,
   imageSignature,
-  { runFn = run, runVerboseFn = runVerbose } = {}
+  {
+    engine,
+    runFn = runEngine,
+    runSafeFn = runSafeEngine,
+    runVerboseFn = runVerboseEngine,
+    env = process.env
+  } = {}
 ) {
-  const hostUid = runFn('id', ['-u']);
-  const hostGid = runFn('id', ['-g']);
+  const { uid: hostUid, gid: hostGid } = resolveBuildUid({
+    engine,
+    runFn,
+    runSafeFn,
+    env
+  });
 
-  runVerboseFn('docker', [
+  runVerboseFn(engine, 'docker', [
     'build',
     '-t',
     config.imageName,
@@ -795,8 +949,8 @@ export function buildImage(
     '--label',
     `${sandboxImageConfigLabel(config)}=${imageSignature}`,
     '-f',
-    dockerfilePath,
-    config.repoRoot
+    toEnginePath(engine, dockerfilePath),
+    toEnginePath(engine, config.repoRoot)
   ], { cwd: config.repoRoot });
 }
 
@@ -821,6 +975,9 @@ export async function create(args) {
     throw new Error(USAGE);
   }
 
+  validateSelinuxDisableEnv();
+  validateClaudeCredentialsEnvOverride();
+
   const config = loadConfig();
   const [branchOrTaskId, base] = positionals;
   const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
@@ -848,9 +1005,12 @@ export async function create(args) {
   );
   const container = containerName(effectiveConfig, branch);
   const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0];
+  const shareCommon = shareCommonDir(effectiveConfig);
+  const shareBranch = shareBranchDir(effectiveConfig, branch);
   const preparedDockerfile = prepareDockerfile(effectiveConfig);
   const baseBranch = base ?? runSafe('git', ['-C', effectiveConfig.repoRoot, 'branch', '--show-current']);
   const expectedImageSignature = buildSignature(preparedDockerfile, tools);
+  const engine = detectEngine(effectiveConfig);
 
   p.intro(pc.cyan('AI Sandbox'));
   p.log.info(
@@ -864,9 +1024,9 @@ export async function create(args) {
     });
     p.log.success('Docker is ready');
 
-    const imageExists = runOk('docker', ['image', 'inspect', effectiveConfig.imageName]);
+    const imageExists = runOkEngine(engine, 'docker', ['image', 'inspect', effectiveConfig.imageName]);
     const currentImageSignature = imageExists
-      ? runSafe('docker', [
+      ? runSafeEngine(engine, 'docker', [
         'image',
         'inspect',
         '--format',
@@ -882,7 +1042,8 @@ export async function create(args) {
         effectiveConfig,
         tools,
         preparedDockerfile.path,
-        expectedImageSignature
+        expectedImageSignature,
+        { engine }
       );
       p.log.success(imageExists ? 'Image rebuilt' : 'Image built');
     } else {
@@ -911,10 +1072,26 @@ export async function create(args) {
 
           if (branchExists) {
             message(`Using existing branch '${branch}'...`);
-            runTaskCommand('git', ['-C', effectiveConfig.repoRoot, 'worktree', 'add', worktree, branch]);
+            runEngineTaskCommand(engine, 'git', [
+              '-C',
+              toEnginePath(engine, effectiveConfig.repoRoot),
+              'worktree',
+              'add',
+              toEnginePath(engine, worktree),
+              branch
+            ]);
           } else {
             message(`Creating branch '${branch}' from '${baseBranch}'...`);
-            runTaskCommand('git', ['-C', effectiveConfig.repoRoot, 'worktree', 'add', '-b', branch, worktree, baseBranch]);
+            runEngineTaskCommand(engine, 'git', [
+              '-C',
+              toEnginePath(engine, effectiveConfig.repoRoot),
+              'worktree',
+              'add',
+              '-b',
+              branch,
+              toEnginePath(engine, worktree),
+              baseBranch
+            ]);
           }
 
           return `Worktree ready at ${worktree}`;
@@ -947,8 +1124,15 @@ export async function create(args) {
                 continue;
               }
               let content = fs.readFileSync(filePath, 'utf8');
-              content = content.replaceAll(effectiveConfig.repoRoot, '/workspace');
-              content = content.replaceAll(effectiveConfig.home, path.dirname(tool.containerMount));
+              const containerHome = path.posix.dirname(tool.containerMount);
+              for (const hostPath of [effectiveConfig.repoRoot, effectiveConfig.home]) {
+                const replacement = hostPath === effectiveConfig.repoRoot ? '/workspace' : containerHome;
+                content = content.replaceAll(hostPath, replacement);
+                const posixHostPath = hostPath.replaceAll('\\', '/');
+                if (posixHostPath !== hostPath) {
+                  content = content.replaceAll(posixHostPath, replacement);
+                }
+              }
               fs.writeFileSync(filePath, content, 'utf8');
             }
           }
@@ -959,15 +1143,15 @@ export async function create(args) {
       {
         title: `Starting container '${container}'`,
         task: async (message) => {
-          const existing = runSafe('docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
+          const existing = runSafeEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
           const matchedContainers = containerNameCandidates(effectiveConfig, branch)
             .filter((name) => existing.includes(name));
 
           if (matchedContainers.length > 0) {
             message('Removing old container instance...');
             for (const name of matchedContainers) {
-              runSafe('docker', ['stop', name]);
-              runSafe('docker', ['rm', name]);
+              runSafeEngine(engine, 'docker', ['stop', name]);
+              runSafeEngine(engine, 'docker', ['rm', name]);
             }
           }
 
@@ -993,73 +1177,112 @@ export async function create(args) {
               signingKey
             )
             : null;
-          const envArgs = buildContainerEnvArgs(resolvedTools);
-          const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
-          if (claudeCodeEntry) {
-            ensureClaudeOnboarding(claudeCodeEntry.dir);
-            ensureClaudeSettings(claudeCodeEntry.dir);
-            // Credential availability is asserted up-front in create() so we
-            // know the shared credentials file already exists at this point.
-          }
-          const codexEntry = resolvedTools.find(({ tool }) => tool.id === 'codex');
-          if (codexEntry) {
-            ensureCodexWorkspaceTrust(codexEntry.dir);
-          }
-          const geminiEntry = resolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
-          if (geminiEntry) {
-            ensureGeminiWorkspaceTrust(geminiEntry.dir);
+          const envFile = buildContainerEnvFile(resolvedTools, engine);
+          let hostShellConfig;
+          try {
+            const claudeCodeEntry = resolvedTools.find(({ tool }) => tool.id === 'claude-code');
+            if (claudeCodeEntry) {
+              ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
+              ensureClaudeSettings(claudeCodeEntry.dir, effectiveConfig.home);
+              // Credential availability is asserted up-front in create() so we
+              // know the shared credentials file already exists at this point.
+            }
+            const codexEntry = resolvedTools.find(({ tool }) => tool.id === 'codex');
+            if (codexEntry) {
+              ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
+              ensureCodexWorkspaceTrust(codexEntry.dir);
+            }
+            const geminiEntry = resolvedTools.find(({ tool }) => tool.id === 'gemini-cli');
+            if (geminiEntry) {
+              ensureGeminiWorkspaceTrust(geminiEntry.dir);
+            }
+            const opencodeEntry = resolvedTools.find(({ tool }) => tool.id === 'opencode');
+            if (opencodeEntry) {
+              // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.
+              ensureOpenCodeModelInheritance(opencodeEntry.dir, effectiveConfig.home);
+            }
+            const toolVolumes = resolvedTools.flatMap(({ tool, dir }) => [
+              '-v',
+              volumeArg(engine, dir, tool.containerMount)
+            ]);
+            const workspaceDir = path.join(effectiveConfig.repoRoot, '.agents', 'workspace');
+            hostShellConfig = prepareHostShellConfig({
+              home: effectiveConfig.home,
+              project: effectiveConfig.project,
+              branch,
+              repoRoot: effectiveConfig.repoRoot
+            });
+            const shellConfigVolumes = hostShellConfig.mounts.flatMap(({ hostPath, containerPath }) => [
+              '-v',
+              volumeArg(engine, hostPath, containerPath, ':ro')
+            ]);
+            const liveMountVolumes = resolvedTools.flatMap(({ tool }) =>
+              (tool.hostLiveMounts ?? [])
+                .filter(({ hostPath }) => fs.existsSync(hostPath))
+                .flatMap(({ hostPath, containerSubpath }) => [
+                  '-v',
+                  volumeArg(engine, hostPath, path.posix.join(tool.containerMount, containerSubpath))
+                ])
+            );
+
+            fs.mkdirSync(workspaceDir, { recursive: true });
+            fs.mkdirSync(shareCommon, { recursive: true });
+            fs.mkdirSync(shareBranch, { recursive: true });
+
+            const dotfilesSnapshot = materializeDotfiles(
+              effectiveConfig.dotfilesDir,
+              dotfilesCacheDir(effectiveConfig.home, effectiveConfig.project)
+            );
+            const dotfilesMount = dotfilesSnapshot
+              ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
+              : [];
+
+            runEngineTaskCommand(engine, 'docker', [
+              'run',
+              '-d',
+              '--name',
+              container,
+              '--hostname',
+              `${effectiveConfig.project}-sandbox`,
+              '--label',
+              sandboxLabel(effectiveConfig),
+              '--label',
+              `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
+              '-v',
+              volumeArg(engine, worktree, '/workspace'),
+              '-v',
+              volumeArg(engine, workspaceDir, '/workspace/.agents/workspace'),
+              '-v',
+              volumeArg(engine, shareCommon, '/share/common'),
+              '-v',
+              volumeArg(engine, shareBranch, '/share/branch'),
+              '-v',
+              volumeArg(
+                engine,
+                path.join(effectiveConfig.repoRoot, '.git'),
+                `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`
+              ),
+              '-v',
+              volumeArg(engine, hostJoin(effectiveConfig.home, '.ssh'), '/home/devuser/.ssh', ':ro'),
+              ...dotfilesMount,
+              ...toolVolumes,
+              ...liveMountVolumes,
+              ...shellConfigVolumes,
+              ...envFile.dockerArgs,
+              '-w',
+              '/workspace',
+              effectiveConfig.imageName
+            ]);
+          } finally {
+            envFile.cleanup();
           }
-          // OpenCode has no workspace trust mechanism, so no preseed step is needed.
-          const toolVolumes = resolvedTools.flatMap(({ tool, dir }) => ['-v', `${dir}:${tool.containerMount}`]);
-          const workspaceDir = path.join(effectiveConfig.repoRoot, '.agents', 'workspace');
-          const hostShellConfig = prepareHostShellConfig({
-            home: effectiveConfig.home,
-            project: effectiveConfig.project,
-            branch,
-            repoRoot: effectiveConfig.repoRoot
-          });
-          const shellConfigVolumes = hostShellConfig.mounts.flatMap(({ hostPath, containerPath }) => [
-            '-v',
-            `${hostPath}:${containerPath}:ro`
-          ]);
-          const liveMountVolumes = resolvedTools.flatMap(({ tool }) =>
-            (tool.hostLiveMounts ?? [])
-              .filter(({ hostPath }) => fs.existsSync(hostPath))
-              .flatMap(({ hostPath, containerSubpath }) => [
-                '-v',
-                `${hostPath}:${path.join(tool.containerMount, containerSubpath)}`
-              ])
-          );
-
-          fs.mkdirSync(workspaceDir, { recursive: true });
-
-          runTaskCommand('docker', [
-            'run',
-            '-d',
-            '--name',
-            container,
-            '--hostname',
-            `${effectiveConfig.project}-sandbox`,
-            '--label',
-            sandboxLabel(effectiveConfig),
-            '--label',
-            `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
-            '-v',
-            `${worktree}:/workspace`,
-            '-v',
-            `${workspaceDir}:/workspace/.agents/workspace`,
-            '-v',
-            `${effectiveConfig.repoRoot}/.git:${effectiveConfig.repoRoot}/.git`,
-            '-v',
-            `${path.join(effectiveConfig.home, '.ssh')}:/home/devuser/.ssh:ro`,
-            ...toolVolumes,
-            ...liveMountVolumes,
-            ...shellConfigVolumes,
-            ...envArgs,
-            '-w',
-            '/workspace',
-            effectiveConfig.imageName
-          ]);
+
+          // Belt-and-suspenders: re-create the four shell-config symlinks at
+          // runtime so users with a custom `sandbox.dockerfile` (which won't
+          // include the ai-tools.dockerfile symlink fragment) still get
+          // ~/.gitconfig and friends pointing into the host bind-mount.
+          // `ln -sf` is idempotent for the default image.
+          ensureShellConfigSymlinks(engine, container);
 
           if (needsGpg) {
             message(
@@ -1079,7 +1302,9 @@ export async function create(args) {
                 {
                   cachedOverride: cachedGpg,
                   repoPath: worktree,
-                  signingKey
+                  signingKey,
+                  dockerExecFn: (cmd, args, opts) => execEngine(engine, cmd, args, opts),
+                  dockerRunSafeFn: (cmd, args, opts) => runSafeEngine(engine, cmd, args, opts)
                 }
               )) {
                 writeSanitizedGitconfig({
@@ -1106,7 +1331,7 @@ export async function create(args) {
 
           for (const { tool } of resolvedTools) {
             for (const command of tool.postSetupCmds ?? []) {
-              runSafe('docker', ['exec', container, 'bash', '-lc', command]);
+              runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
             }
           }
 
@@ -1119,18 +1344,18 @@ export async function create(args) {
   }
 
   p.log.step('Verifying setup...');
-  const runningContainers = runSafe('docker', ['ps', '--format', '{{.Names}}']).split('\n');
+  const runningContainers = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
   const checks = [
     { name: 'Container running', ok: runningContainers.includes(container) },
     ...runtimeChecks(effectiveConfig.runtimes).map((check) => ({
       name: check.name,
-      ok: runOk('docker', ['exec', container, ...check.cmd])
+      ok: runOkEngine(engine, 'docker', ['exec', container, ...check.cmd])
     })),
-    { name: 'GitHub CLI', ok: runOk('docker', ['exec', container, 'gh', '--version']) }
+    { name: 'GitHub CLI', ok: runOkEngine(engine, 'docker', ['exec', container, 'gh', '--version']) }
   ];
   const toolChecks = tools.map((tool) => ({
     name: tool.name,
-    ok: runOk('docker', ['exec', container, 'bash', '-lc', tool.versionCmd]),
+    ok: runOkEngine(engine, 'docker', ['exec', container, 'bash', '-lc', tool.versionCmd]),
     hint: tool.setupHint
   }));
 
@@ -1159,6 +1384,8 @@ Container: ${container}
 Image: ${effectiveConfig.imageName}
 Worktree: ${worktree}
 Host aliases: ${sandboxAliasesPath(effectiveConfig.home)}
+Share (common): ${shareCommon} -> /share/common
+Share (branch): ${shareBranch} -> /share/branch
 
 Management:
   ai sandbox ls
@@ -1166,7 +1393,7 @@ Management:
   ai sandbox rm ${branch}
 
 Sandbox aliases:
-  Edit the host aliases file to customize shortcuts mounted at ${CONTAINER_HOME}/.bash_aliases.
+  Edit the host aliases file to customize shortcuts exposed at ${CONTAINER_HOME}/.bash_aliases inside the sandbox container.
 
 Tool notes:
 ${toolHints}