@fitlab-ai/agent-infra 0.6.4 → 0.6.5

package/dist/lib/sandbox/readme-scaffold.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { shareBranchDir, shareCommonDir } from "./constants.js";
+const DOTFILES_README = `# User-level dotfiles channel
+
+This directory is mounted **read-only** into every sandbox container at
+\`/dotfiles\`. On entry, \`sandbox-dotfiles-link\` mirrors every file here as a
+symlink under \`$HOME\` (e.g. \`.tmux.conf\` -> \`/home/devuser/.tmux.conf\`),
+overriding image defaults so your editor, shell, and tool preferences follow
+you across \`ai sandbox destroy + create\`.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#user-level-dotfiles-channel
+
+Common usage - drop files or symlinks here:
+
+\`\`\`sh
+# Real files
+echo "set -g mouse on" > ~/.agent-infra/dotfiles/.tmux.conf
+
+# Symlinks to live host paths
+ln -s ~/.tmux.conf       ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit  ~/.agent-infra/dotfiles/.config/lazygit
+\`\`\`
+
+> Do **not** put secrets here. Use the dedicated SSH / credential mounts.
+
+If you delete this file, the next \`ai sandbox create\` will re-create it
+verbatim. To stop seeing it, edit or empty the file in place - the scaffold
+only writes \`README.md\` when it is missing, never when it already exists.
+
+---
+
+# 用户级 dotfiles 通道
+
+该目录被以**只读**方式挂载到每个 sandbox 容器的 \`/dotfiles\`。容器启动时，
+\`sandbox-dotfiles-link\` 会把这里的每个文件 \`ln -sfn\` 到 \`$HOME\` 对应路径
+（例如 \`.tmux.conf -> /home/devuser/.tmux.conf\`），覆盖镜像默认值，让你的编辑器、
+shell、工具偏好跨 \`ai sandbox destroy + create\` 持久存在。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#用户级-dotfiles-通道
+
+常见用法：把文件或符号链接放进来：
+
+\`\`\`sh
+# 直接放文件
+echo "set -g mouse on" > ~/.agent-infra/dotfiles/.tmux.conf
+
+# 用符号链接指向 host 实际文件
+ln -s ~/.tmux.conf       ~/.agent-infra/dotfiles/.tmux.conf
+ln -s ~/.config/lazygit  ~/.agent-infra/dotfiles/.config/lazygit
+\`\`\`
+
+> **不要**在此放任何凭证。SSH / 凭证请使用专用挂载通道。
+
+如果你删除该文件，下一次 \`ai sandbox create\` 会原样重新生成。如果你不想再
+看到它，**就地编辑或清空内容**即可：scaffold 仅在 \`README.md\` **缺失**时
+写入，文件存在（哪怕被清空）就不会被重写。
+`;
+const SHARE_COMMON_README = `# /share/common - host <-> sandbox shared scratch (cross-branch)
+
+This directory is mounted **read-write** into every sandbox container of this
+project at \`/share/common\`, regardless of branch. Drop files here to share
+between host and any sandbox without polluting the git worktree.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+
+This file is safe to delete; the next \`ai sandbox create\` will re-create it.
+
+---
+
+# /share/common - 宿主 <-> sandbox 共享暂存（跨分支）
+
+该目录被以**读写**方式挂载到本项目所有 sandbox 容器的 \`/share/common\`，
+跨分支可见。可用来在宿主和任意 sandbox 之间传文件，无需弄脏 git worktree。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+
+该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
+`;
+const SHARE_BRANCH_README = `# /share/branch - host <-> sandbox shared scratch (branch-exclusive)
+
+This directory is mounted **read-write** into the sandbox container of this
+project's current branch at \`/share/branch\`. Files here are exclusive to this
+branch's sandbox and do not leak across branches.
+
+See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+
+This file is safe to delete; the next \`ai sandbox create\` will re-create it.
+
+---
+
+# /share/branch - 宿主 <-> sandbox 共享暂存（分支独占）
+
+该目录被以**读写**方式挂载到本项目当前分支 sandbox 容器的 \`/share/branch\`，
+仅当前分支可见，不会跨分支泄漏。
+
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+
+该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
+`;
+function errorDetail(error) {
+    return error instanceof Error ? error.message : 'unknown error';
+}
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : '';
+}
+function ensureFile(target, content, options) {
+    const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
+    const fsModule = options.fsModule ?? fs;
+    const result = { created: false, path: target };
+    try {
+        fsModule.mkdirSync(path.dirname(target), { recursive: true });
+    }
+    catch (error) {
+        writeStderr(`sandbox-readme-scaffold: skipping ${target} (${errorDetail(error)})\n`);
+        return result;
+    }
+    try {
+        fsModule.writeFileSync(target, content, { encoding: 'utf8', flag: 'wx' });
+        result.created = true;
+    }
+    catch (error) {
+        if (errorCode(error) === 'EEXIST') {
+            return result;
+        }
+        writeStderr(`sandbox-readme-scaffold: skipping ${target} (${errorDetail(error)})\n`);
+    }
+    return result;
+}
+export function ensureDotfilesReadme(dotfilesDir, options = {}) {
+    return ensureFile(path.join(dotfilesDir, 'README.md'), DOTFILES_README, options);
+}
+export function ensureShareCommonReadme(config, options = {}) {
+    return ensureFile(path.join(shareCommonDir(config), 'README.md'), SHARE_COMMON_README, options);
+}
+export function ensureShareBranchReadme(config, branch, options = {}) {
+    return ensureFile(path.join(shareBranchDir(config, branch), 'README.md'), SHARE_BRANCH_README, options);
+}
+export function ensureSandboxDiscoveryReadmes(config, branch, options = {}) {
+    return [
+        ensureDotfilesReadme(config.dotfilesDir, options),
+        ensureShareCommonReadme(config, options),
+        ensureShareBranchReadme(config, branch, options)
+    ];
+}
+//# sourceMappingURL=readme-scaffold.js.map

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

@@ -1,4 +1,6 @@
 USER devuser
+ENV DISABLE_UPDATES=1
+ENV OPENCODE_DISABLE_AUTOUPDATE=1
 ENV NPM_CONFIG_PREFIX=/home/devuser/.npm-global
 ENV PATH="/home/devuser/.npm-global/bin:${PATH}"
 

package/dist/lib/sandbox/runtimes/base.dockerfile

@@ -1,4 +1,4 @@
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 
 LABEL description="AI coding sandbox"
 
@@ -28,7 +28,7 @@ RUN apt-get update && apt-get install -y \
     && 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 \
-    && TMUX_VERSION=3.6a \
+    && TMUX_VERSION=3.6b \
     && wget -qO /tmp/tmux.tar.gz \
         "https://github.com/tmux/tmux/releases/download/${TMUX_VERSION}/tmux-${TMUX_VERSION}.tar.gz" \
     && tar xzf /tmp/tmux.tar.gz -C /tmp \
@@ -126,7 +126,7 @@ find . -type f -print | while IFS= read -r rel; do
     .config/opencode|.config/opencode/*|\
     .local/share/opencode|.local/share/opencode/*|\
     .host-shell-config|.host-shell-config/*|\
-    .gitconfig|.gitignore_global|.stCommitMsg|.bash_aliases)
+    .gitconfig|.gitignore_global|.stCommitMsg|.bash_aliases|README.md)
       continue ;;
   esac
 

package/lib/cp.ts

@@ -0,0 +1,177 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import { platform as currentPlatform, tmpdir as defaultTmpdir } from 'node:os';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { createClipboardAdapter, type ClipboardAdapter } from './sandbox/clipboard/index.ts';
+
+const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS NSPasteboard over ssh/scp.\n';
+const COMMAND_TIMEOUT_MS = 30_000;
+
+export type SpawnResult = {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+};
+
+type SpawnFn = (cmd: string, args: string[], input?: string) => SpawnResult;
+type CreateAdapterFn = (options?: { platformName?: NodeJS.Platform }) => ClipboardAdapter | null;
+type MkDTempFn = (prefix: string) => string;
+type WriteFileFn = (file: string, data: Buffer) => void;
+type RmFn = (target: string, options: { recursive: boolean; force: boolean }) => void;
+
+export type CpDeps = {
+  platform?: NodeJS.Platform;
+  createAdapter?: CreateAdapterFn;
+  spawnFn?: SpawnFn;
+  randomId?: () => string;
+  mkdtempFn?: MkDTempFn;
+  writeFileFn?: WriteFileFn;
+  rmFn?: RmFn;
+  tmpdir?: () => string;
+  writeStdout?: (chunk: string) => unknown;
+  writeStderr?: (chunk: string) => unknown;
+};
+
+export function runCommand(cmd: string, args: string[], input?: string): SpawnResult {
+  const result = spawnSync(cmd, args, {
+    input,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: COMMAND_TIMEOUT_MS
+  });
+
+  return {
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    error: result.error
+  };
+}
+
+export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number> {
+  const {
+    platform = currentPlatform(),
+    createAdapter = createClipboardAdapter,
+    spawnFn = runCommand,
+    randomId = randomUUID,
+    mkdtempFn = fs.mkdtempSync,
+    writeFileFn = fs.writeFileSync,
+    rmFn = fs.rmSync,
+    tmpdir = defaultTmpdir,
+    writeStdout = (chunk: string) => process.stdout.write(chunk),
+    writeStderr = (chunk: string) => process.stderr.write(chunk)
+  } = deps;
+
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    writeStdout(USAGE);
+    return 0;
+  }
+
+  let positionals: string[];
+  try {
+    ({ positionals } = parseArgs({ args, allowPositionals: true, strict: true }));
+  } catch {
+    writeStderr(USAGE);
+    return 1;
+  }
+
+  const alias = positionals[0];
+  if (!alias || positionals.length !== 1) {
+    writeStderr(USAGE);
+    return 1;
+  }
+  if (alias.startsWith('-')) {
+    writeStderr(`invalid ssh alias '${alias}': must not start with '-'\n`);
+    return 1;
+  }
+
+  if (platform !== 'darwin') {
+    writeStderr(`ai cp currently supports macOS senders only (got ${platform})\n`);
+    return 1;
+  }
+
+  const adapter = createAdapter({ platformName: platform });
+  const png = adapter?.readImagePng() ?? null;
+  if (png === null) {
+    writeStderr('no image on clipboard\n');
+    return 1;
+  }
+
+  let uploaded = false;
+  let localTmpDir: string | null = null;
+  let remotePath: string | null = null;
+
+  try {
+    localTmpDir = mkdtempFn(path.join(tmpdir(), 'agent-infra-cp-'));
+    const localPng = path.join(localTmpDir, 'clipboard.png');
+    writeFileFn(localPng, png);
+
+    remotePath = `/tmp/agent-infra-cp-${randomId()}.png`;
+    const upload = spawnFn('scp', [
+      '-o',
+      'BatchMode=yes',
+      '-o',
+      'ConnectTimeout=10',
+      localPng,
+      `${alias}:${remotePath}`
+    ]);
+    if (upload.status !== 0) {
+      writeStderr(`failed to upload image to ${alias}:\n${commandDetail(upload)}\n`);
+      return 1;
+    }
+    uploaded = true;
+
+    // Remote write currently targets macOS only: it pipes an AppleScript to the
+    // remote `osascript` to set its NSPasteboard. This is the extension point for
+    // other remote platforms later (e.g. dispatch on remote OS to wl-copy/xclip
+    // on Linux); a non-macOS remote fails here with a clear non-zero error today.
+    const setRemote = spawnFn('ssh', [
+      '-o',
+      'BatchMode=yes',
+      '-o',
+      'ConnectTimeout=10',
+      alias,
+      'osascript',
+      '-'
+    ], remoteSetScript(remotePath));
+    if (setRemote.status !== 0) {
+      writeStderr(`failed to set remote clipboard on ${alias}:\n${commandDetail(setRemote)}\n`);
+      return 1;
+    }
+
+    writeStdout(`copied clipboard image to ${alias}\n`);
+    return 0;
+  } finally {
+    if (uploaded && remotePath) {
+      spawnFn('ssh', [
+        '-o',
+        'BatchMode=yes',
+        '-o',
+        'ConnectTimeout=10',
+        alias,
+        'rm',
+        '-f',
+        remotePath
+      ]);
+    }
+    if (localTmpDir) {
+      rmFn(localTmpDir, { recursive: true, force: true });
+    }
+  }
+}
+
+function commandDetail(result: SpawnResult): string {
+  const detail = result.stderr || result.error?.message || result.stdout || 'unknown error';
+  return detail.trimEnd();
+}
+
+function remoteSetScript(remotePath: string): string {
+  const escapedPath = remotePath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return [
+    `set theFile to POSIX file "${escapedPath}"`,
+    'set the clipboard to (read theFile as «class PNGf»)'
+  ].join('\n');
+}

package/lib/sandbox/clipboard/bridge.ts

@@ -1,4 +1,5 @@
 import { StringDecoder } from 'node:string_decoder';
+import { spawnSync } from 'node:child_process';
 import { createClipboardAdapter, type ClipboardAdapter } from './index.ts';
 import { buildBracketedPaste, CtrlVDetector, type CtrlVMatch } from './keys.ts';
 import {
@@ -32,6 +33,26 @@ type BridgeOptions = {
 const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
 const PARTIAL_ESCAPE_FLUSH_MS = 30;
 
+// Node's stdin.setRawMode(true) uses libuv's RAW mode, which (unlike the
+// cfmakeraw that `docker exec -it` applies on the non-bridge path) keeps ONLCR
+// set on the shared host TTY. With ONLCR on, the kernel rewrites the bare \n
+// that tmux emits after homing the cursor inside the right pane into \r\n,
+// snapping the cursor to column 1 so the following erase/redraw wipes the left
+// pane. Clearing OPOST brings the host TTY in line with the non-bridge path.
+// Best-effort: setRawMode(false) on teardown restores the original termios, and
+// a missing/failed stty only reinstates the redraw glitch.
+function disableOutputPostProcessing(stdin: NodeJS.ReadStream): void {
+  const candidate = (stdin as { fd?: unknown }).fd;
+  if (typeof candidate !== 'number') {
+    return;
+  }
+  try {
+    spawnSync('stty', ['-opost'], { stdio: [candidate, 'ignore', 'ignore'] });
+  } catch {
+    // stty unavailable or fd is not a tty; leave the terminal as-is.
+  }
+}
+
 export async function runInteractiveWithClipboardBridge(options: BridgeOptions): Promise<number> {
   const {
     engine,
@@ -56,14 +77,11 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
     return runInteractive(engine, 'docker', dockerArgs);
   }
 
-  if (platformName !== 'darwin') {
-    return runInteractive(engine, 'docker', dockerArgs);
-  }
   if (!stdin.isTTY || !stdout.isTTY) {
     return fallback('host stdin/stdout is not a TTY');
   }
   if (!adapter) {
-    return fallback('macOS clipboard adapter is unavailable');
+    return fallback('no clipboard adapter available on this platform');
   }
   const available = adapter.available();
   if (!available.ok) {
@@ -185,6 +203,7 @@ async function runBridge({
 
   try {
     stdin.setRawMode?.(true);
+    disableOutputPostProcessing(stdin);
     stdin.resume();
     stdin.on('data', onData);
     stdout.on('resize', onResize);

package/lib/sandbox/clipboard/index.ts

@@ -6,8 +6,17 @@ export type ClipboardAdapter = DarwinClipboardAdapter;
 export function createClipboardAdapter({
   platformName = platform()
 }: { platformName?: NodeJS.Platform } = {}): ClipboardAdapter | null {
-  if (platformName !== 'darwin') {
-    return null;
+  switch (platformName) {
+    case 'darwin':
+      return createDarwinClipboardAdapter();
+    case 'linux':
+      // Future work: dispatch based on $WAYLAND_DISPLAY (wl-paste) or $DISPLAY (xclip);
+      // see Issue #386 follow-up. Returning null disables the bridge for now.
+      return null;
+    case 'win32':
+      // Future work: native Win32 clipboard reader. Returning null disables the bridge.
+      return null;
+    default:
+      return null;
   }
-  return createDarwinClipboardAdapter();
 }

package/lib/sandbox/commands/create.ts

@@ -43,6 +43,7 @@ import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
+import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.ts';
 import {
   prepareClaudeCredentials,
   redactCommandError,
@@ -1287,6 +1288,13 @@ export async function create(args: string[]): Promise<void> {
             message(`Created default sandbox aliases at ${aliasesFile.path}`);
           }
 
+          const readmeResults = ensureSandboxDiscoveryReadmes(effectiveConfig, branch);
+          for (const { created, path: readmePath } of readmeResults) {
+            if (created) {
+              message(`Created discovery README at ${readmePath}`);
+            }
+          }
+
           const gitconfigPath = path.join(effectiveConfig.home, '.gitconfig');
           const gitconfigContent = fs.existsSync(gitconfigPath)
             ? fs.readFileSync(gitconfigPath, 'utf8')

package/lib/sandbox/commands/enter.ts

@@ -45,6 +45,37 @@ export function hostTimezoneEnvFlags(detect = detectHostTimezone): string[] {
   return tz ? ['-e', `TZ=${tz}`] : [];
 }
 
+export function clipboardBridgeDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = (env.AI_SANDBOX_NO_CLIPBOARD_BRIDGE ?? '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
+export function runSandboxInteractive(params: {
+  engine: string;
+  dockerArgs: string[];
+  container: string;
+  home: string;
+  env?: NodeJS.ProcessEnv;
+  runBridge?: typeof runInteractiveWithClipboardBridge;
+  runInteractive?: typeof runInteractiveEngine;
+}): number | Promise<number> {
+  const {
+    engine,
+    dockerArgs,
+    container,
+    home,
+    env = process.env,
+    runBridge = runInteractiveWithClipboardBridge,
+    runInteractive = runInteractiveEngine
+  } = params;
+
+  if (clipboardBridgeDisabled(env)) {
+    return runInteractive(engine, 'docker', dockerArgs);
+  }
+
+  return runBridge({ engine, dockerArgs, container, home });
+}
+
 export function formatCredentialSyncStatus(
   result: ReturnType<typeof reconcileClaudeCredentials>,
   isTTY = process.stderr.isTTY
@@ -115,9 +146,10 @@ export async function enter(args: string[]): Promise<number> {
       process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
     }
 
-    return runInteractiveWithClipboardBridge({
+    const dockerArgs = ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH];
+    return runSandboxInteractive({
       engine,
-      dockerArgs: ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH],
+      dockerArgs,
       container,
       home: config.home
     });

package/lib/sandbox/commands/rebuild.ts

@@ -13,7 +13,7 @@ import type { SandboxTool } from '../tools.ts';
 import { toEnginePath } from '../engines/wsl2-paths.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 
-const USAGE = `Usage: ai sandbox rebuild [--quiet]`;
+const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh]`;
 
 type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
 type EngineRunFn = (engine: string, cmd: string, args: string[], opts?: { cwd?: string }) => string;
@@ -38,12 +38,14 @@ export function buildArgs(
     engine,
     runFn = runEngine,
     runSafeFn = runSafeEngine,
-    env = process.env
+    env = process.env,
+    refresh = false
   }: {
     engine?: string;
     runFn?: EngineRunFn;
     runSafeFn?: EngineRunSafeFn;
     env?: NodeJS.ProcessEnv;
+    refresh?: boolean;
   } = {}
 ): string[] {
   const selectedEngine = engine ?? detectEngine(config);
@@ -54,7 +56,7 @@ export function buildArgs(
     env
   });
 
-  return [
+  const args = [
     'build',
     '-t',
     config.imageName,
@@ -72,6 +74,12 @@ export function buildArgs(
     toEnginePath(selectedEngine, dockerfilePath),
     toEnginePath(selectedEngine, config.repoRoot)
   ];
+
+  if (refresh) {
+    args.splice(1, 0, '--no-cache', '--pull');
+  }
+
+  return args;
 }
 
 function removeImageIfPresent(imageName: string, engine: string): void {
@@ -86,6 +94,7 @@ export async function rebuild(args: string[]): Promise<void> {
     allowPositionals: true,
     strict: true,
     options: {
+      refresh: { type: 'boolean' },
       quiet: { type: 'boolean', short: 'q' },
       help: { type: 'boolean', short: 'h' }
     }
@@ -101,6 +110,7 @@ export async function rebuild(args: string[]): Promise<void> {
   const preparedDockerfile = prepareDockerfile(config);
   const imageSignature = buildSignature(preparedDockerfile, tools);
   const quiet = values.quiet ?? false;
+  const refresh = values.refresh ?? false;
   const engine = detectEngine(config);
 
   await ensureDocker(config, undefined);
@@ -113,7 +123,7 @@ export async function rebuild(args: string[]): Promise<void> {
       removeImageIfPresent(config.imageName, engine);
       spinner.stop('Old image removed');
       spinner.start('Building image...');
-      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }), {
+      runEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), {
         cwd: config.repoRoot
       });
       spinner.stop(pc.green('Sandbox image rebuilt'));
@@ -124,7 +134,7 @@ export async function rebuild(args: string[]): Promise<void> {
       runVerboseEngine(
         engine,
         'docker',
-        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }),
+        buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }),
         { cwd: config.repoRoot }
       );
       p.log.success(pc.green('Sandbox image rebuilt'));

package/lib/sandbox/index.ts

@@ -3,12 +3,13 @@ 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
-  refresh                      Sync host Claude Code credentials to all sandbox copies
   ls                           List sandboxes for the current project
-  rm <branch> [--all]          Remove a sandbox or all sandboxes
   prune [--dry-run]            Remove orphaned per-branch state dirs
+  rebuild [--quiet] [--refresh]
+                               Rebuild the sandbox image (--refresh pulls base + tools)
+  refresh                      Sync host Claude Code credentials to all sandbox copies
+  rm <branch> [--all]          Remove a sandbox or all sandboxes
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
-  rebuild [--quiet]            Rebuild the sandbox image
 
 Run 'ai sandbox <command> --help' for details.`;