@fitlab-ai/agent-infra 0.5.8 → 0.5.10

package/lib/sandbox/commands/enter.js

@@ -1,31 +1,19 @@
 import { loadConfig } from '../config.js';
 import { assertValidBranchName, containerNameCandidates } from '../constants.js';
-import { runInteractive, runSafe } from '../shell.js';
+import { detectEngine } from '../engine.js';
+import {
+  formatCredentialWarnings,
+  formatRemaining,
+  reconcileClaudeCredentials,
+  redactCommandError,
+  validateClaudeCredentialsEnvOverride
+} from '../credentials.js';
+import { runInteractiveEngine, runSafeEngine } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
+import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
 
 const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
-export const TMUX_ENTRY_SCRIPT = `
-SESSION=work
-
-if ! command -v tmux >/dev/null 2>&1; then
-  exec bash
-fi
-
-if ! tmux has-session -t "$SESSION" 2>/dev/null; then
-  exec tmux new-session -s "$SESSION"
-fi
-
-tmux list-sessions -F '#{session_name} #{session_attached}' 2>/dev/null | \\
-  while read -r name attached; do
-    [ "$name" = "$SESSION" ] && continue
-    case "$name" in
-      ''|*[!0-9]*) continue ;;
-    esac
-    [ "$attached" = "0" ] && tmux kill-session -t "$name" 2>/dev/null || true
-  done
-
-exec tmux new-session -t "$SESSION"
-`.trim();
+const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
 // inspect to enable progressive enhancements such as the kitty keyboard
@@ -50,6 +38,30 @@ export function terminalEnvFlags(env = process.env) {
   return flags;
 }
 
+export function formatCredentialSyncStatus(result, isTTY = process.stderr.isTTY) {
+  if (result.status === 'STALE_ACCESS') {
+    return 'Warning: Claude Code credentials on host appear stale. Run "ai sandbox refresh" or "claude /login" to renew.\n';
+  }
+  if (result.status === 'MISSING') {
+    return 'Warning: Claude Code credentials missing on host. Run "claude /login" to authenticate.\n';
+  }
+  if (result.status === 'KEYCHAIN_WRITE_FAILED') {
+    return `Warning: A sandbox refresh produced newer credentials but host Keychain write failed (${formatCredentialWarnings(result.warnings)}). Run "ai sandbox refresh" again or "claude /status" on the host to retry.\n`;
+  }
+  if (result.status === 'KEYCHAIN_LOCKED' || result.status === 'KEYCHAIN_ERROR') {
+    return 'Warning: Host keychain is unavailable; Claude credential sync skipped. Run "ai sandbox refresh" for details.\n';
+  }
+  if (result.status === 'OK' && result.authoritative !== 'host') {
+    const message = `Synced Claude Code credentials from sandbox refresh back to host (expires in ${formatRemaining(result.expiresAt)})`;
+    return isTTY ? `\x1b[2m${message}\x1b[0m\n` : `${message}\n`;
+  }
+  if (result.status === 'OK' && result.filesWritten.length > 0) {
+    const message = `Synced Claude Code credentials from host Keychain (expires in ${formatRemaining(result.expiresAt)})`;
+    return isTTY ? `\x1b[2m${message}\x1b[0m\n` : `${message}\n`;
+  }
+  return null;
+}
+
 export function enter(args) {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(`${USAGE}\n`);
@@ -60,20 +72,41 @@ export function enter(args) {
   }
 
   const config = loadConfig();
+  validateClaudeCredentialsEnvOverride();
+  const engine = detectEngine(config);
   const [branchOrTaskId, ...cmd] = args;
   const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
   assertValidBranchName(branch);
-  const running = runSafe('docker', ['ps', '--format', '{{.Names}}']).split('\n');
+  const running = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
   const container = containerNameCandidates(config, branch).find((name) => running.includes(name));
 
   if (!container) {
     throw new Error(`No running sandbox found for branch '${branch}'`);
   }
 
+  if (config.tools.includes('claude-code')) {
+    try {
+      // Scan all projects so a refresh from a neighbouring sandbox can still flow back to the host.
+      const result = reconcileClaudeCredentials(config.home);
+      const message = formatCredentialSyncStatus(result);
+      if (message) {
+        process.stderr.write(message);
+      }
+    } catch (error) {
+      process.stderr.write(`Warning: Failed to sync Claude Code credentials: ${redactCommandError(error?.message ?? 'unknown error')}\n`);
+    }
+  }
+
   const envFlags = terminalEnvFlags();
   if (cmd.length === 0) {
-    return runInteractive('docker', ['exec', '-it', ...envFlags, container, 'bash', '-c', TMUX_ENTRY_SCRIPT]);
+    try {
+      materializeDotfiles(config.dotfilesDir, dotfilesCacheDir(config.home, config.project));
+    } catch (error) {
+      process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error?.message ?? 'unknown error')}\n`);
+    }
+
+    return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH]);
   }
 
-  return runInteractive('docker', ['exec', '-it', ...envFlags, container, ...cmd]);
+  return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, ...cmd]);
 }

package/lib/sandbox/commands/ls.js

@@ -3,11 +3,37 @@ import path from 'node:path';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.js';
-import { sandboxLabel } from '../constants.js';
-import { runSafe } from '../shell.js';
+import { sandboxBranchLabel, sandboxLabel } from '../constants.js';
+import { detectEngine } from '../engine.js';
+import { runSafeEngine } from '../shell.js';
 import { resolveTools, toolProjectDirCandidates } from '../tools.js';
 
 const USAGE = 'Usage: ai sandbox ls';
+const CONTAINER_LIST_HEADER = 'NAMES\tSTATUS\tBRANCH';
+
+// Exported to lock the docker/podman-compatible format in unit tests.
+export function containerListFormat() {
+  return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
+}
+
+export function parseLabels(csv) {
+  if (!csv) {
+    return {};
+  }
+
+  const labels = {};
+  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;
+}
 
 function listChildren(dir) {
   if (!fs.existsSync(dir)) {
@@ -24,25 +50,30 @@ export function ls(args = []) {
   }
 
   const config = loadConfig();
+  const engine = detectEngine(config);
   const tools = resolveTools(config);
   const label = sandboxLabel(config);
-  const containers = runSafe('docker', [
+  const containers = runSafeEngine(engine, 'docker', [
     'ps',
     '-a',
     '--filter',
     `label=${label}`,
     '--format',
-    'table {{.Names}}\t{{.Status}}\t{{.Label "' + `${label}.branch` + '"}}'
+    containerListFormat()
   ]);
 
   p.intro(pc.cyan(`Sandbox status for ${config.project}`));
 
   p.log.step('Containers');
-  if (!containers || containers.split('\n').length <= 1) {
+  if (!containers) {
     p.log.warn('  No sandbox containers');
   } else {
+    const branchKey = sandboxBranchLabel(config);
+    process.stdout.write(`  ${CONTAINER_LIST_HEADER}\n`);
     for (const line of containers.split('\n')) {
-      process.stdout.write(`  ${line}\n`);
+      const [name = '', status = '', labelsCsv = ''] = line.split('\t');
+      const branch = parseLabels(labelsCsv)[branchKey] ?? '';
+      process.stdout.write(`  ${name}\t${status}\t${branch}\n`);
     }
   }
 

package/lib/sandbox/commands/rebuild.js

@@ -5,9 +5,11 @@ import pc from 'picocolors';
 import { loadConfig } from '../config.js';
 import { prepareDockerfile } from '../dockerfile.js';
 import { sandboxImageConfigLabel, sandboxLabel } from '../constants.js';
-import { ensureDocker } from '../engine.js';
-import { run, runOk, runVerbose } from '../shell.js';
+import { detectEngine, ensureDocker } from '../engine.js';
+import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.js';
 import { resolveTools, toolNpmPackagesArg } from '../tools.js';
+import { toEnginePath } from '../engines/wsl2-paths.js';
+import { resolveBuildUid } from '../engines/native.js';
 
 const USAGE = `Usage: ai sandbox rebuild [--quiet]`;
 
@@ -21,9 +23,19 @@ function buildSignature(preparedDockerfile, tools) {
     .slice(0, 12);
 }
 
-function buildArgs(config, tools, dockerfilePath, imageSignature) {
-  const hostUid = run('id', ['-u']);
-  const hostGid = run('id', ['-g']);
+export function buildArgs(
+  config,
+  tools,
+  dockerfilePath,
+  imageSignature,
+  { engine, runFn = runEngine, runSafeFn = runSafeEngine, env = process.env } = {}
+) {
+  const { uid: hostUid, gid: hostGid } = resolveBuildUid({
+    engine,
+    runFn,
+    runSafeFn,
+    env
+  });
 
   return [
     'build',
@@ -40,14 +52,14 @@ function buildArgs(config, tools, dockerfilePath, imageSignature) {
     '--label',
     `${sandboxImageConfigLabel(config)}=${imageSignature}`,
     '-f',
-    dockerfilePath,
-    config.repoRoot
+    toEnginePath(engine, dockerfilePath),
+    toEnginePath(engine, config.repoRoot)
   ];
 }
 
-function removeImageIfPresent(imageName) {
-  if (runOk('docker', ['image', 'inspect', imageName])) {
-    run('docker', ['rmi', imageName]);
+function removeImageIfPresent(imageName, engine) {
+  if (runOkEngine(engine, 'docker', ['image', 'inspect', imageName])) {
+    runEngine(engine, 'docker', ['rmi', imageName]);
   }
 }
 
@@ -72,6 +84,7 @@ export async function rebuild(args) {
   const preparedDockerfile = prepareDockerfile(config);
   const imageSignature = buildSignature(preparedDockerfile, tools);
   const quiet = values.quiet ?? false;
+  const engine = detectEngine(config);
 
   await ensureDocker(config);
   p.intro(pc.cyan('Rebuilding sandbox image'));
@@ -80,18 +93,21 @@ export async function rebuild(args) {
     if (quiet) {
       const spinner = p.spinner();
       spinner.start(`Removing old image ${config.imageName}...`);
-      removeImageIfPresent(config.imageName);
+      removeImageIfPresent(config.imageName, engine);
       spinner.stop('Old image removed');
       spinner.start('Building image...');
-      run('docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature), { cwd: config.repoRoot });
+      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }), {
+        cwd: config.repoRoot
+      });
       spinner.stop(pc.green('Sandbox image rebuilt'));
     } else {
       p.log.step(`Removing old image ${config.imageName}`);
-      removeImageIfPresent(config.imageName);
+      removeImageIfPresent(config.imageName, engine);
       p.log.step('Building image');
-      runVerbose(
+      runVerboseEngine(
+        engine,
         'docker',
-        buildArgs(config, tools, preparedDockerfile.path, imageSignature),
+        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }),
         { cwd: config.repoRoot }
       );
       p.log.success(pc.green('Sandbox image rebuilt'));

package/lib/sandbox/commands/refresh.js

@@ -0,0 +1,119 @@
+import { homedir } from 'node:os';
+import { parseArgs } from 'node:util';
+import {
+  buildLockedGuidance,
+  discoverProjects,
+  formatCredentialWarnings,
+  formatRemaining,
+  reconcileClaudeCredentials,
+  redactCommandError,
+  validateClaudeCredentialsEnvOverride
+} from '../credentials.js';
+import { runProbe } from '../shell.js';
+
+const USAGE = 'Usage: ai sandbox refresh';
+
+export function probeClaudeStatus(spawnFn = runProbe) {
+  const result = spawnFn('claude', ['/status'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 30_000
+  });
+  return {
+    ok: result.status === 0,
+    stderr: result.stderr ?? '',
+    error: result.error?.message ?? null
+  };
+}
+
+export async function refresh(args, deps = {}) {
+  const {
+    spawnFn = runProbe,
+    execFn,
+    readFn,
+    existsFn,
+    writeFn,
+    writeHostFn,
+    discoverFn = discoverProjects,
+    writeStdout = (chunk) => process.stdout.write(chunk),
+    writeStderr = (chunk) => process.stderr.write(chunk)
+  } = deps;
+
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    writeStdout(`${USAGE}\n`);
+    return 0;
+  }
+
+  const { positionals } = parseArgs({ args, allowPositionals: true, strict: true });
+  if (positionals.length > 0) {
+    throw new Error(USAGE);
+  }
+  validateClaudeCredentialsEnvOverride();
+
+  const home = homedir();
+  if (!home) {
+    throw new Error('sandbox: home directory is required');
+  }
+
+  const projects = discoverFn(home);
+  if (projects.length === 0) {
+    writeStdout('No project credentials to refresh.\n');
+    return 0;
+  }
+
+  const reconcileOptions = { execFn, readFn, existsFn, writeFn, writeHostFn, projects };
+  let result = reconcileClaudeCredentials(home, reconcileOptions);
+  if (result.status === 'STALE_ACCESS' && result.authoritative === null) {
+    writeStdout('Host credentials appear stale; probing claude /status to trigger refresh...\n');
+    const probe = probeClaudeStatus(spawnFn);
+    if (!probe.ok) {
+      writeStderr(`Probe failed: ${redactCommandError(probe.stderr || probe.error || 'unknown error')}\n`);
+      writeStderr('Run "claude /login" on the host to renew credentials.\n');
+      return 1;
+    }
+    writeStdout('Probe succeeded; re-inspecting host credentials.\n');
+    result = reconcileClaudeCredentials(home, reconcileOptions);
+  }
+
+  if (result.status === 'MISSING') {
+    writeStderr('No Claude Code credentials found on host.\n');
+    writeStderr('Run "claude /login" on the host to authenticate.\n');
+    return 1;
+  }
+
+  if (result.status === 'KEYCHAIN_LOCKED') {
+    writeStderr(`${buildLockedGuidance()}\n`);
+    return 1;
+  }
+
+  if (result.status === 'KEYCHAIN_ERROR') {
+    writeStderr(`Host keychain error: ${redactCommandError(result.detail || 'unknown error')}\n`);
+    writeStderr(`${buildLockedGuidance()}\n`);
+    return 1;
+  }
+
+  if (result.status === 'KEYCHAIN_WRITE_FAILED') {
+    writeStderr(`[host] keychain write failed: ${formatCredentialWarnings(result.warnings) || 'unknown error'}\n`);
+    return 1;
+  }
+
+  if (result.status !== 'OK') {
+    writeStderr('Host credentials still invalid after probe; run "claude /login".\n');
+    return 1;
+  }
+
+  if (result.authoritative && result.authoritative !== 'host' && result.hostWritten) {
+    writeStdout(`[host] reconciled from ${result.authoritative}\n`);
+  }
+
+  for (const project of projects) {
+    const action = result.filesWritten.includes(project) ? 'updated' : 'unchanged';
+    writeStdout(`[${project}] ${action}; expires in ${formatRemaining(result.expiresAt)}\n`);
+  }
+
+  for (const failure of result.fileErrors) {
+    writeStderr(`[${failure.project}] sync failed: ${failure.error}\n`);
+  }
+
+  return result.fileErrors.length > 0 ? 1 : 0;
+}

package/lib/sandbox/commands/rm.js

@@ -9,10 +9,11 @@ import {
   containerNameCandidates,
   sandboxBranchLabel,
   sandboxLabel,
+  shareBranchDir,
   worktreeDirCandidates
 } from '../constants.js';
-import { detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.js';
-import { run, runOk, runSafe } from '../shell.js';
+import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedVm } from '../engine.js';
+import { run, runOk, runSafe, runSafeEngine } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
 import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.js';
 
@@ -22,8 +23,20 @@ function projectToolDirs(config, tools) {
   return tools.flatMap((tool) => toolProjectDirCandidates(tool, config.project));
 }
 
+export function assertManagedPath(root, target) {
+  const resolvedRoot = path.resolve(root);
+  const resolvedTarget = path.resolve(target);
+  const relative = path.relative(resolvedRoot, resolvedTarget);
+  if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
+    return;
+  }
+
+  throw new Error(`Refusing to remove path outside managed sandbox root: ${target}`);
+}
+
 async function rmOne(config, tools, branch) {
   assertValidBranchName(branch);
+  const engine = detectEngine(config);
   let effectiveBranch = branch;
   let worktreeCandidates = worktreeDirCandidates(config, branch);
   let toolCandidates = tools.map((tool) => ({
@@ -33,12 +46,12 @@ async function rmOne(config, tools, branch) {
 
   p.intro(pc.cyan(`Removing sandbox for ${branch}`));
 
-  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(config, branch)
     .filter((name) => existing.includes(name));
 
   if (matchedContainers.length > 0) {
-    const resolvedBranch = runSafe('docker', [
+    const resolvedBranch = runSafeEngine(engine, 'docker', [
       'inspect',
       '-f',
       `{{ index .Config.Labels "${sandboxBranchLabel(config)}" }}`,
@@ -56,8 +69,8 @@ async function rmOne(config, tools, branch) {
     const spinner = p.spinner();
     spinner.start(`Stopping container(s): ${matchedContainers.join(', ')}`);
     for (const name of matchedContainers) {
-      runSafe('docker', ['stop', name]);
-      runSafe('docker', ['rm', name]);
+      runSafeEngine(engine, 'docker', ['stop', name]);
+      runSafeEngine(engine, 'docker', ['rm', name]);
     }
     spinner.stop(pc.green(`Removed container(s): ${matchedContainers.join(', ')}`));
   } else {
@@ -81,6 +94,7 @@ async function rmOne(config, tools, branch) {
         try {
           run('git', ['-C', config.repoRoot, 'worktree', 'remove', worktree, '--force']);
         } catch {
+          assertManagedPath(config.worktreeBase, worktree);
           fs.rmSync(worktree, { recursive: true, force: true });
         }
       }
@@ -100,18 +114,33 @@ async function rmOne(config, tools, branch) {
 
   for (const { tool, candidates } of toolCandidates) {
     for (const dir of candidates.filter((candidate) => fs.existsSync(candidate))) {
+      assertManagedPath(tool.sandboxBase, dir);
       fs.rmSync(dir, { recursive: true, force: true });
       p.log.success(`${tool.name} state removed: ${dir}`);
     }
   }
 
+  const shareBranch = shareBranchDir(config, effectiveBranch);
+  if (fs.existsSync(shareBranch)) {
+    const shouldRemoveShare = await p.confirm({
+      message: `Remove share dir for branch '${effectiveBranch}' (${shareBranch})?`,
+      initialValue: true
+    });
+    if (!p.isCancel(shouldRemoveShare) && shouldRemoveShare) {
+      assertManagedPath(config.shareBase, shareBranch);
+      fs.rmSync(shareBranch, { recursive: true, force: true });
+      p.log.success(`Share dir removed: ${shareBranch}`);
+    }
+  }
+
   p.outro(pc.green('Sandbox removed'));
 }
 
 async function rmAll(config, tools) {
+  const engine = detectEngine(config);
   p.intro(pc.cyan(`Removing all sandboxes for ${config.project}`));
 
-  const containers = runSafe('docker', [
+  const containers = runSafeEngine(engine, 'docker', [
     'ps',
     '-a',
     '--filter',
@@ -123,8 +152,8 @@ async function rmAll(config, tools) {
     const spinner = p.spinner();
     spinner.start('Stopping project sandbox containers...');
     for (const name of containers.split('\n').filter(Boolean)) {
-      runSafe('docker', ['stop', name]);
-      runSafe('docker', ['rm', name]);
+      runSafeEngine(engine, 'docker', ['stop', name]);
+      runSafeEngine(engine, 'docker', ['rm', name]);
     }
     spinner.stop(pc.green('Project sandbox containers removed'));
   } else {
@@ -143,6 +172,7 @@ async function rmAll(config, tools) {
         try {
           run('git', ['-C', config.repoRoot, 'worktree', 'remove', dir, '--force']);
         } catch {
+          assertManagedPath(config.worktreeBase, dir);
           fs.rmSync(dir, { recursive: true, force: true });
         }
       }
@@ -152,21 +182,39 @@ async function rmAll(config, tools) {
 
   for (const dir of projectToolDirs(config, tools)) {
     if (fs.existsSync(dir)) {
+      assertManagedPath(path.dirname(dir), dir);
       fs.rmSync(dir, { recursive: true, force: true });
       p.log.success(`Removed tool state: ${dir}`);
     }
   }
 
+  if (fs.existsSync(config.shareBase) && fs.readdirSync(config.shareBase).length > 0) {
+    const shouldRemoveAllShares = await p.confirm({
+      message: `Remove all share dirs for project (${config.shareBase})?`,
+      initialValue: true
+    });
+    if (!p.isCancel(shouldRemoveAllShares) && shouldRemoveAllShares) {
+      assertManagedPath(path.dirname(config.shareBase), config.shareBase);
+      fs.rmSync(config.shareBase, { recursive: true, force: true });
+      p.log.success(`Project share dirs removed: ${config.shareBase}`);
+    }
+  }
+
   const shouldRemoveImage = await p.confirm({
     message: `Remove image ${config.imageName}?`,
     initialValue: false
   });
   if (!p.isCancel(shouldRemoveImage) && shouldRemoveImage) {
-    runSafe('docker', ['rmi', config.imageName]);
+    runSafeEngine(engine, 'docker', ['rmi', config.imageName]);
   }
 
-  const engine = detectEngine(config);
   if (isManagedEngine(engine)) {
+    if (engine === ENGINES.WSL2) {
+      p.log.warn('Windows uses Docker Desktop with WSL2. Stop it from Docker Desktop or run "wsl --shutdown" manually.');
+      p.outro(pc.green('All project sandboxes removed'));
+      return;
+    }
+
     const name = engineDisplayName(engine);
     const shouldStopVm = await p.confirm({
       message: `Stop ${name} VM?`,

package/lib/sandbox/commands/vm.js

@@ -7,20 +7,38 @@ import {
   ENGINES,
   detectEngine,
   engineDisplayName,
-  ensureDocker,
   isManagedEngine,
+  startManagedVm,
   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(engine) {
+export function ensureManagedVm(engine) {
+  if (engine === ENGINES.NATIVE) {
+    throw new Error(
+      "Linux native Docker does not use a managed VM. Use 'ai sandbox create' directly."
+    );
+  }
+
   if (!isManagedEngine(engine)) {
-    throw new Error(`VM management is unavailable for engine '${engineDisplayName(engine)}'.`);
+    throw new Error(
+      `VM management is unavailable for engine '${engineDisplayName(engine)}'. `
+      + (engine === ENGINES.DOCKER_DESKTOP
+        ? 'Docker Desktop is managed via its GUI (Settings -> Resources).'
+        : '')
+    );
   }
 }
 
+export function wsl2BackendStatus({ runOkFn = runOk } = {}) {
+  const wslAvailable = runOkFn('wsl.exe', ['--status']) || runOkFn('wsl.exe', ['--', 'true']);
+  const dockerAvailable = wslAvailable && runOkFn('wsl.exe', ['--', 'docker', 'info']);
+
+  return { wslAvailable, dockerAvailable };
+}
+
 function status() {
   const config = loadConfig();
   const engine = detectEngine(config);
@@ -28,6 +46,22 @@ function status() {
   ensureManagedVm(engine);
   p.intro(pc.cyan('Sandbox VM status'));
 
+  if (engine === ENGINES.WSL2) {
+    const backend = wsl2BackendStatus();
+    if (backend.wslAvailable) {
+      p.log.info('WSL2 is available');
+    } else {
+      p.log.warn('WSL2 is not available. Install WSL2 and configure a default Linux distribution.');
+    }
+
+    if (backend.dockerAvailable) {
+      p.log.info('Docker Desktop WSL integration is available');
+    } else {
+      p.log.warn('Docker is not available inside WSL2. Start Docker Desktop and enable WSL integration.');
+    }
+    return;
+  }
+
   if (engine === ENGINES.COLIMA) {
     if (runOk('colima', ['status'])) {
       process.stdout.write(`${runSafe('colima', ['status'])}\n`);
@@ -65,6 +99,16 @@ async function start(args) {
   const config = loadConfig();
   const engine = detectEngine(config);
   ensureManagedVm(engine);
+
+  p.intro(pc.cyan('Starting sandbox VM'));
+  if (engine === ENGINES.WSL2) {
+    p.log.warn(
+      'WSL2 Docker backend is managed by Docker Desktop. '
+      + 'Start it from Docker Desktop GUI, then run "ai sandbox vm status" to check readiness.'
+    );
+    return;
+  }
+
   const effectiveConfig = {
     ...config,
     vm: {
@@ -74,10 +118,11 @@ async function start(args) {
     }
   };
 
-  p.intro(pc.cyan('Starting sandbox VM'));
-  await ensureDocker(effectiveConfig, (detail) => {
+  const onMessage = (detail) => {
     p.log.info(detail);
-  });
+  };
+
+  startManagedVm(effectiveConfig, { onMessage });
   p.outro(pc.green('VM ready'));
 }
 
@@ -88,6 +133,11 @@ function stop() {
   ensureManagedVm(engine);
   p.intro(pc.cyan('Stopping sandbox VM'));
 
+  if (engine === ENGINES.WSL2) {
+    p.log.warn('Windows uses Docker Desktop with WSL2. Stop it from Docker Desktop or run "wsl --shutdown" manually.');
+    return;
+  }
+
   if (engine === ENGINES.COLIMA && !runOk('colima', ['status'])) {
     p.log.warn(`${name} VM is not running`);
     return;