@fitlab-ai/agent-infra 0.6.4 → 0.6.5

package/README.md

@@ -202,9 +202,13 @@ This detects the packaged template version and renders all managed files. The sa
 
 The sandbox image also preinstalls `gh`. When `gh auth token` succeeds on the host, `ai sandbox create` injects the token into the container as `GH_TOKEN`, so `gh` commands work inside the sandbox without extra setup.
 
+`ai sandbox rebuild` keeps Docker's build cache by default, so it quickly retags the sandbox image without refreshing every package. Use `ai sandbox rebuild --refresh` when you want to upgrade the image: it passes `--no-cache --pull` to Docker, pulls the current Ubuntu base image, and reruns the apt, tmux build, and global npm install layers. Claude Code updates are disabled inside the container, and OpenCode startup update checks are disabled; `--refresh` is the routine upgrade path for sandbox-managed tools. Manual `opencode upgrade` remains outside this guard. The default `python3` provided by the Ubuntu 24.04 sandbox base is Python 3.12, so scripts that hard-code Python 3.10 paths may need adjustment.
+
 `ai sandbox exec` also forwards a small terminal-detection whitelist (`TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LC_TERMINAL`, `LC_TERMINAL_VERSION`) into the container. This keeps interactive TUIs aligned with the host terminal for behaviors such as Claude Code's Shift+Enter newline support, without passing through the full host environment.
 
-On macOS, interactive `ai sandbox exec <branch>` sessions can bridge image paste into the sandbox. When you press `Ctrl+V` and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under `~/.agent-infra/clipboard/`, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the `/clipboard` mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path.
+On macOS, interactive `ai sandbox exec <branch>` sessions can bridge image paste into the sandbox. When you press `Ctrl+V` and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under `~/.agent-infra/clipboard/`, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the `/clipboard` mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path. Set `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` to skip the bridge and enter the normal interactive path directly when diagnosing mouse, scrolling, or other input issues.
+
+When you run the sandbox from a remote Mac over SSH, use `ai cp <ssh-alias>` on the Mac in front of you to push the local clipboard image to that remote Mac first. Copy an image with Cmd+C, run `ai cp mini`, then return to the existing SSH session and press `Ctrl+V`; the sandbox bridge reads the remote Mac's NSPasteboard and injects the image as usual. This command handles PNG images only and uses non-interactive ssh/scp with key-based authentication. For now both the sender and the remote must be macOS—the remote NSPasteboard is written via `osascript`—but the remote-write step is the natural extension point for other platforms later.
 
 `ai sandbox exec` and `ai sandbox refresh` reconcile Claude Code credentials in both directions across the host credential store and every sandbox project copy under `~/.agent-infra/credentials/*`. When a long-running sandbox refreshes OAuth tokens first, the next entry or refresh command writes the freshest valid copy back to the host Keychain or `~/.claude/.credentials.json`; when the host is fresher, it updates the project copies. If every copy is stale, `ai sandbox refresh` probes `claude /status` and asks you to log in only when the probe cannot recover credentials.
 
@@ -230,6 +234,11 @@ remove only dirs without an active sandbox container.
 Existing sandboxes pick up these mounts after `ai sandbox rm <branch>` and
 `ai sandbox create <branch>`.
 
+On first `ai sandbox create`, agent-infra writes a bilingual `README.md` into
+`~/.agent-infra/share/<project>/common/` and each `branches/<branch>/`
+directory to help you discover these channels. The READMEs are idempotent and
+can be safely deleted; the scaffold only writes them when missing.
+
 ### User-level dotfiles channel
 
 `ai sandbox create` also mounts an optional read-only channel for host user preferences:
@@ -294,6 +303,7 @@ target.
 | `.config/opencode/*`, `.local/share/opencode/*` | OpenCode credentials and data use dedicated bind mounts. |
 | `.host-shell-config/*` | agent-infra managed shell and Git configuration. |
 | `.gitconfig`, `.gitignore_global`, `.stCommitMsg`, `.bash_aliases` | agent-infra symlinks these to `.host-shell-config/`, including `safe.directory` and GPG sync state. |
+| `README.md` | agent-infra scaffolds a discoverability README at the dotfiles root on first create; the link hook ignores it so `$HOME/README.md` is not shadowed. |
 
 Other existing real directories, such as `~/.config/` or `~/.cache/`, are not
 replaced by top-level dotfiles. If a file conflicts with one of those
@@ -787,7 +797,7 @@ The generated `.agents/.airc.json` file is the central contract between the boot
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.4",
+  "templateVersion": "v0.6.5",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -202,9 +202,13 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 沙箱镜像也会预装 `gh`。如果宿主机上的 `gh auth token` 能成功返回 token，`ai sandbox create` 会把它以 `GH_TOKEN` 环境变量注入容器，让你在沙箱里直接使用 `gh`，无需额外登录配置。
 
+`ai sandbox rebuild` 默认保留 Docker build cache，因此会快速重打沙箱镜像，不会刷新每个软件包。需要升级镜像时使用 `ai sandbox rebuild --refresh`：它会向 Docker 传入 `--no-cache --pull`，重新拉取当前 Ubuntu 基础镜像，并重跑 apt、tmux 编译和全局 npm 安装层。容器内 Claude Code 更新已关闭，OpenCode 启动时更新检查也已关闭；`--refresh` 是沙箱托管工具的常规升级入口。手动 `opencode upgrade` 不受该保护覆盖。Ubuntu 24.04 沙箱基础镜像提供的默认 `python3` 是 Python 3.12，因此硬编码 Python 3.10 路径的脚本可能需要调整。
+
 `ai sandbox exec` 也会向容器透传一小组终端检测白名单变量（`TERM_PROGRAM`、`TERM_PROGRAM_VERSION`、`LC_TERMINAL`、`LC_TERMINAL_VERSION`）。这样可以让交互式 TUI 保持与宿主终端一致的行为，例如 Claude Code 的 `Shift+Enter` 换行支持，同时避免把整个宿主环境灌入容器。
 
-在 macOS 上，交互式 `ai sandbox exec <branch>` 会尽力桥接宿主图片粘贴。当你按下 `Ctrl+V` 且宿主剪贴板当前是图片时，agent-infra 会从宿主剪贴板读取图片，将 PNG 写到 `~/.agent-infra/clipboard/`，再以 bracketed paste 注入容器内路径，让 Claude Code、Codex、Gemini CLI 和 OpenCode 按图片附件处理。宿主剪贴板只读，不会被改写。该能力会自动降级：已有沙箱需要重建后才有 `/clipboard` 挂载；如果可选 pty 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。
+在 macOS 上，交互式 `ai sandbox exec <branch>` 会尽力桥接宿主图片粘贴。当你按下 `Ctrl+V` 且宿主剪贴板当前是图片时，agent-infra 会从宿主剪贴板读取图片，将 PNG 写到 `~/.agent-infra/clipboard/`，再以 bracketed paste 注入容器内路径，让 Claude Code、Codex、Gemini CLI 和 OpenCode 按图片附件处理。宿主剪贴板只读，不会被改写。该能力会自动降级：已有沙箱需要重建后才有 `/clipboard` 挂载；如果可选 pty 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。排查鼠标、滚动或其他输入异常时，可以设置 `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` 跳过桥接，直接进入原本的交互路径。
+
+当你通过 SSH 在远端 Mac 上运行沙箱时，可先在手边这台 Mac 上执行 `ai cp <ssh-alias>`，把本机剪贴板图片推送到远端 Mac。典型流程是：Cmd+C 复制图片，运行 `ai cp mini`，回到已有 SSH session 后按 `Ctrl+V`；沙箱桥会读取远端 Mac 的 NSPasteboard，并按原路径注入图片。该命令只处理 PNG 图片，并使用基于 ssh key 的非交互 ssh/scp。目前发送端与远端都需为 macOS（远端通过 `osascript` 写入 NSPasteboard），后续可扩展支持其他远端平台。
 
 `ai sandbox exec` 和 `ai sandbox refresh` 会在宿主机凭证存储与 `~/.agent-infra/credentials/*` 下的所有沙箱项目副本之间做双向 reconcile。长时间运行的沙箱如果先刷新了 OAuth token，下一次进入或刷新命令会把最新有效副本回写到宿主 Keychain 或 `~/.claude/.credentials.json`；宿主机更新时也会继续覆盖项目副本。如果所有副本都已失效，`ai sandbox refresh` 会尝试 `claude /status` 探活，只有探活无法恢复时才提示重新登录。
 
@@ -220,6 +224,11 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 可先用 `ai sandbox prune --dry-run` 查看旧版本或异常中断遗留的孤儿 per-branch 状态目录，再用 `ai sandbox prune` 只删除没有活跃 sandbox 容器对应的目录。
 已有沙箱需要执行 `ai sandbox rm <branch>` 后再执行 `ai sandbox create <branch>`，才能加载新的挂载点。
 
+首次执行 `ai sandbox create` 时，agent-infra 会在
+`~/.agent-infra/share/<project>/common/` 以及每个 `branches/<branch>/`
+目录下写入一份中英双语 `README.md`，帮助你发现这些通道。README 是幂等的，
+可以安全删除；scaffold 仅在文件缺失时写入。
+
 #### 用户级 dotfiles 通道
 
 `ai sandbox create` 还会自动挂载一条可选的只读通道，用于把宿主机用户级偏好带进沙箱：
@@ -270,6 +279,7 @@ dotfiles 树解引用到
 | `.config/opencode/*`, `.local/share/opencode/*` | OpenCode 凭证和数据使用专用 bind mount。 |
 | `.host-shell-config/*` | agent-infra 管理的 shell 和 Git 配置。 |
 | `.gitconfig`, `.gitignore_global`, `.stCommitMsg`, `.bash_aliases` | agent-infra 将这些路径软链到 `.host-shell-config/`，包含 `safe.directory` 和 GPG 同步状态。 |
+| `README.md` | agent-infra 会在 dotfiles 根目录 scaffold 一份发现性 README；link hook 会忽略它，避免遮蔽 `$HOME/README.md`。 |
 
 其他已经存在的真实目录（如 `~/.config/`、`~/.cache/`）不会被顶层 dotfile 替换。如果某个文件与这类目录冲突，钩子会打印警告并跳过：
 
@@ -760,7 +770,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.4",
+  "templateVersion": "v0.6.5",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/bin/cli.ts

@@ -13,12 +13,13 @@ if (major < 22) {
 const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
 Usage:
-  agent-infra init        Initialize a new project with update-agent-infra seed command
-  agent-infra merge       Merge tasks from another workspace directory (active/blocked/completed/archive)
-  agent-infra update      Update seed files and sync file registry for an existing project
-  agent-infra sandbox     Manage Docker-based AI sandboxes
-  agent-infra version     Show version
-  agent-infra help        Show this help message
+  agent-infra cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  agent-infra help            Show this help message
+  agent-infra init            Initialize a new project with update-agent-infra seed command
+  agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
+  agent-infra sandbox         Manage Docker-based AI sandboxes
+  agent-infra update          Update seed files and sync file registry for an existing project
+  agent-infra version         Show version
 
 Shorthand: ai (e.g. ai init)
 
@@ -96,6 +97,17 @@ switch (command) {
     });
     break;
   }
+  case 'cp': {
+    const imported = await importCommand('../lib/cp.ts');
+    if (!imported) break;
+    const { cmdCp } = imported;
+    const code = await cmdCp(process.argv.slice(3)).catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
+      return 1;
+    });
+    if (code) process.exitCode = code;
+    break;
+  }
   case 'version': {
     if (process.argv[3] === '--raw') {
       console.log(VERSION);

package/dist/bin/cli.js

@@ -17,12 +17,13 @@ if (major < 22) {
 const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
 Usage:
-  agent-infra init        Initialize a new project with update-agent-infra seed command
-  agent-infra merge       Merge tasks from another workspace directory (active/blocked/completed/archive)
-  agent-infra update      Update seed files and sync file registry for an existing project
-  agent-infra sandbox     Manage Docker-based AI sandboxes
-  agent-infra version     Show version
-  agent-infra help        Show this help message
+  agent-infra cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  agent-infra help            Show this help message
+  agent-infra init            Initialize a new project with update-agent-infra seed command
+  agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
+  agent-infra sandbox         Manage Docker-based AI sandboxes
+  agent-infra update          Update seed files and sync file registry for an existing project
+  agent-infra version         Show version
 
 Shorthand: ai (e.g. ai init)
 
@@ -99,6 +100,19 @@ switch (command) {
         });
         break;
     }
+    case 'cp': {
+        const imported = await importCommand('../lib/cp.ts');
+        if (!imported)
+            break;
+        const { cmdCp } = imported;
+        const code = await cmdCp(process.argv.slice(3)).catch((e) => {
+            process.stderr.write(`Error: ${errorMessage(e)}\n`);
+            return 1;
+        });
+        if (code)
+            process.exitCode = code;
+        break;
+    }
     case 'version': {
         if (process.argv[3] === '--raw') {
             console.log(VERSION);

package/dist/lib/cp.js

@@ -0,0 +1,127 @@
+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 } from "./sandbox/clipboard/index.js";
+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 function runCommand(cmd, args, input) {
+    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, deps = {}) {
+    const { platform = currentPlatform(), createAdapter = createClipboardAdapter, spawnFn = runCommand, randomId = randomUUID, mkdtempFn = fs.mkdtempSync, writeFileFn = fs.writeFileSync, rmFn = fs.rmSync, tmpdir = defaultTmpdir, 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);
+        return 0;
+    }
+    let positionals;
+    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 = null;
+    let remotePath = 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) {
+    const detail = result.stderr || result.error?.message || result.stdout || 'unknown error';
+    return detail.trimEnd();
+}
+function remoteSetScript(remotePath) {
+    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');
+}
+//# sourceMappingURL=cp.js.map

package/dist/lib/sandbox/clipboard/bridge.js

@@ -1,4 +1,5 @@
 import { StringDecoder } from 'node:string_decoder';
+import { spawnSync } from 'node:child_process';
 import { createClipboardAdapter } from "./index.js";
 import { buildBracketedPaste, CtrlVDetector } from "./keys.js";
 import { clipboardHostDir, containerClipboardPath, pngClipboardFilename, pruneClipboardDir, writeClipboardPngAtomic } from "./paths.js";
@@ -6,20 +7,37 @@ import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine }
 import { loadNodePty } from "./node-pty.js";
 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) {
+    const candidate = stdin.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) {
     const { engine, dockerArgs, container, home, cwd = process.cwd(), env = process.env, platformName = process.platform, adapter = createClipboardAdapter({ platformName }), loadPty = loadNodePty, runInteractive = runInteractiveEngine, runOk = runOkEngine, writeStderr = (chunk) => process.stderr.write(chunk), stdin = process.stdin, stdout = process.stdout, createDetector = () => new CtrlVDetector() } = options;
     function fallback(reason) {
         writeStderr(`${FALLBACK_PREFIX}: ${reason}\n`);
         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) {
@@ -121,6 +139,7 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
     }
     try {
         stdin.setRawMode?.(true);
+        disableOutputPostProcessing(stdin);
         stdin.resume();
         stdin.on('data', onData);
         stdout.on('resize', onResize);

package/dist/lib/sandbox/clipboard/index.js

@@ -1,9 +1,18 @@
 import { platform } from 'node:os';
 import { createDarwinClipboardAdapter } from "./darwin.js";
 export function createClipboardAdapter({ platformName = platform() } = {}) {
-    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();
 }
 //# sourceMappingURL=index.js.map

package/dist/lib/sandbox/commands/create.js

@@ -19,6 +19,7 @@ import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from "../clipboard/paths.
 import { validateSelinuxDisableEnv } from "../engines/selinux.js";
 import { resolveBuildUid } from "../engines/native.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
+import { ensureSandboxDiscoveryReadmes } from "../readme-scaffold.js";
 import { prepareClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
 import { detectHostTimezone } from "../host-timezone.js";
 const OPENCODE_YOLO_PERMISSION = '{"*":"allow","read":"allow","bash":"allow","edit":"allow","webfetch":"allow","external_directory":"allow","doom_loop":"allow"}';
@@ -981,6 +982,12 @@ export async function create(args) {
                     if (aliasesFile.created) {
                         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/dist/lib/sandbox/commands/enter.js

@@ -34,6 +34,17 @@ export function hostTimezoneEnvFlags(detect = detectHostTimezone) {
     const tz = detect();
     return tz ? ['-e', `TZ=${tz}`] : [];
 }
+export function clipboardBridgeDisabled(env = process.env) {
+    const value = (env.AI_SANDBOX_NO_CLIPBOARD_BRIDGE ?? '').trim().toLowerCase();
+    return value === '1' || value === 'true' || value === 'yes';
+}
+export function runSandboxInteractive(params) {
+    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, 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';
@@ -97,9 +108,10 @@ export async function enter(args) {
         catch (error) {
             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/dist/lib/sandbox/commands/rebuild.js

@@ -10,7 +10,7 @@ import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from "../shel
 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]`;
+const USAGE = `Usage: ai sandbox rebuild [--quiet] [--refresh]`;
 function buildSignature(preparedDockerfile, tools) {
     return createHash('sha256')
         .update(JSON.stringify({
@@ -20,7 +20,7 @@ function buildSignature(preparedDockerfile, tools) {
         .digest('hex')
         .slice(0, 12);
 }
-export function buildArgs(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, env = process.env } = {}) {
+export function buildArgs(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, env = process.env, refresh = false } = {}) {
     const selectedEngine = engine ?? detectEngine(config);
     const { uid: hostUid, gid: hostGid } = resolveBuildUid({
         engine: selectedEngine,
@@ -28,7 +28,7 @@ export function buildArgs(config, tools, dockerfilePath, imageSignature, { engin
         runSafeFn,
         env
     });
-    return [
+    const args = [
         'build',
         '-t',
         config.imageName,
@@ -46,6 +46,10 @@ export function buildArgs(config, tools, dockerfilePath, imageSignature, { engin
         toEnginePath(selectedEngine, dockerfilePath),
         toEnginePath(selectedEngine, config.repoRoot)
     ];
+    if (refresh) {
+        args.splice(1, 0, '--no-cache', '--pull');
+    }
+    return args;
 }
 function removeImageIfPresent(imageName, engine) {
     if (runOkEngine(engine, 'docker', ['image', 'inspect', imageName])) {
@@ -58,6 +62,7 @@ export async function rebuild(args) {
         allowPositionals: true,
         strict: true,
         options: {
+            refresh: { type: 'boolean' },
             quiet: { type: 'boolean', short: 'q' },
             help: { type: 'boolean', short: 'h' }
         }
@@ -71,6 +76,7 @@ export async function rebuild(args) {
     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);
     p.intro(pc.cyan('Rebuilding sandbox image'));
@@ -81,7 +87,7 @@ export async function rebuild(args) {
             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'));
@@ -90,7 +96,7 @@ export async function rebuild(args) {
             p.log.step(`Removing old image ${config.imageName}`);
             removeImageIfPresent(config.imageName, engine);
             p.log.step('Building image');
-            runVerboseEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine }), { cwd: config.repoRoot });
+            runVerboseEngine(engine, 'docker', buildArgs(config, tools, preparedDockerfile.path, imageSignature, { engine, refresh }), { cwd: config.repoRoot });
             p.log.success(pc.green('Sandbox image rebuilt'));
         }
     }

package/dist/lib/sandbox/index.js

@@ -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.`;
 export async function runSandbox(args) {