@fitlab-ai/agent-infra 0.6.3 → 0.6.5

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) {

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,9 +1,8 @@
-FROM ubuntu:22.04
+FROM ubuntu:24.04
 
 LABEL description="AI coding sandbox"
 
 ENV DEBIAN_FRONTEND=noninteractive
-ENV TZ=Asia/Shanghai
 
 ARG HOST_UID=1000
 ARG HOST_GID=1000
@@ -22,14 +21,14 @@ RUN apt-get update && apt-get install -y \
     build-essential ca-certificates gnupg lsb-release \
     libevent-core-2.1-7 libncursesw6 libtinfo6 \
     pkg-config bison libevent-dev libncurses-dev \
-    locales \
+    locales tzdata \
     && locale-gen en_US.UTF-8 \
     && (curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
         | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg) \
     && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
         > /etc/apt/sources.list.d/github-cli.list \
     && apt-get update && apt-get install -y gh \
-    && 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 \
@@ -45,13 +44,13 @@ RUN apt-get update && apt-get install -y \
     && rm -rf /var/lib/apt/lists/*
 
 # Enable extended keys in CSI u format so Shift+Enter and other modified
-# keys are forwarded through tmux. Preserve terminal-detection variables
+# keys are forwarded through tmux. Preserve terminal/timezone variables
 # injected at `docker exec` time when new tmux sessions are created.
 RUN printf '%s\n' \
       'set -g extended-keys always' \
       'set -g extended-keys-format csi-u' \
       "set -as terminal-features 'xterm*:extkeys'" \
-      "set -ga update-environment 'TERM_PROGRAM TERM_PROGRAM_VERSION LC_TERMINAL LC_TERMINAL_VERSION'" \
+      "set -ga update-environment 'TERM_PROGRAM TERM_PROGRAM_VERSION LC_TERMINAL LC_TERMINAL_VERSION TZ'" \
       'set -g mouse on' \
       'set -g status-interval 1' \
       'set -g status-right-length 80' \
@@ -127,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
 
@@ -146,7 +145,7 @@ RUN cat > /usr/local/bin/sandbox-tmux-entry <<'SCRIPT' && chmod +x /usr/local/bi
 #!/bin/sh
 set -eu
 
-sandbox-dotfiles-link >/dev/null || true
+sandbox-dotfiles-link >/dev/null 2>&1 || true
 
 SESSION=work
 
@@ -154,20 +153,26 @@ 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
+# Drop stale grouped sessions left by older entry-script versions (the windows
+# live on $SESSION, so killing the group members only removes view entries).
+tmux list-sessions -F '#{session_name}' 2>/dev/null | while IFS= read -r name; do
     case "$name" in
-      ''|*[!0-9]*) continue ;;
+      "$SESSION"-*) tmux kill-session -t "$name" 2>/dev/null || true ;;
     esac
-    [ "$attached" = "0" ] && tmux kill-session -t "$name" 2>/dev/null || true
-  done
+done
+
+# Reuse the single $SESSION; -d detaches any pre-existing client so the new
+# one becomes the sole owner of window-size, eliminating size races.
+if tmux has-session -t "$SESSION" 2>/dev/null; then
+  # Push the per-exec TZ into the running session's env so new
+  # windows/panes pick up the host timezone without a session kill.
+  if [ -n "${TZ:-}" ]; then
+    tmux set-environment -t "$SESSION" TZ "$TZ" 2>/dev/null || true
+  fi
+  exec tmux attach -d -t "$SESSION"
+fi
 
-exec tmux new-session -t "$SESSION"
+exec tmux new-session -s "$SESSION"
 SCRIPT
 
 ENV LANG=en_US.UTF-8

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) {
@@ -153,14 +171,15 @@ async function runBridge({
 
   function handleCtrlV(match: CtrlVMatch, target: PtyProcess): void {
     try {
-      if (!adapter.hasImage()) {
-        target.write(match.raw);
-        return;
-      }
-
+      // readImagePng returns null both for "no image on clipboard" and for
+      // unexpected read failures; both cases forward the original Ctrl+V so
+      // the container app handles it as a regular keystroke. The throw branch
+      // below only fires on truly unexpected exceptions (e.g. fs write
+      // errors writing to the host clipboard dir).
       const png = adapter.readImagePng();
       if (!png) {
-        throw new Error('clipboard image could not be read');
+        target.write(match.raw);
+        return;
       }
       const filename = pngClipboardFilename(png);
       writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
@@ -184,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/darwin.ts

@@ -4,7 +4,12 @@ import os from 'node:os';
 import path from 'node:path';
 import type { ExecFileSyncOptions } from 'node:child_process';
 
-const HAS_IMAGE_TIMEOUT_MS = 500;
+// Quick "is osascript callable at all" probe used by available(). Not for
+// clipboard work — clipboard work shares READ_IMAGE_TIMEOUT_MS below.
+// Generous 2s budget: this is a once-per-session bridge enablement check;
+// failing it just disables the clipboard bridge for that session, so we'd
+// rather tolerate a cold osascript spawn than misreport "unavailable".
+const OSASCRIPT_PROBE_TIMEOUT_MS = 2_000;
 const READ_IMAGE_TIMEOUT_MS = 5_000;
 const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
 
@@ -12,7 +17,14 @@ type ExecFn = (cmd: string, args: string[], options?: ExecFileSyncOptions) => Bu
 
 export type DarwinClipboardAdapter = {
   available(): { ok: true } | { ok: false; reason: string };
-  hasImage(): boolean;
+  // Returns PNG bytes when the clipboard holds (or can synthesize) an image,
+  // null otherwise. No separate hasImage(): a probing `clipboard info` call
+  // forces NSPasteboard to materialize TIFF/BMP/8BPS representations to
+  // report their sizes, which can take seconds when the clipboard holds a
+  // Retina screenshot. Letting AppleScript's `as «class PNGf»` either succeed
+  // (image present, possibly auto-converted from TIFF/JPEG/GIF) or error
+  // (nothing PNG-coercible) keeps the path O(PNG size) regardless of how
+  // many other representations the source declared.
   readImagePng(): Buffer | null;
 };
 
@@ -30,23 +42,12 @@ export function createDarwinClipboardAdapter({
   return {
     available() {
       try {
-        execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: HAS_IMAGE_TIMEOUT_MS });
+        execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: OSASCRIPT_PROBE_TIMEOUT_MS });
         return { ok: true };
       } catch {
         return { ok: false, reason: 'macOS osascript is unavailable' };
       }
     },
-    hasImage() {
-      try {
-        const output = String(execFn('osascript', ['-e', 'clipboard info'], {
-          encoding: 'utf8',
-          timeout: HAS_IMAGE_TIMEOUT_MS
-        }));
-        return /\b(PNGf|TIFF|JPEG|GIFf)\b/.test(output);
-      } catch {
-        return false;
-      }
-    },
     readImagePng() {
       const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
       const outputPath = path.join(tmpDir, 'clipboard.png');

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,11 +43,13 @@ 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,
   validateClaudeCredentialsEnvOverride
 } from '../credentials.ts';
+import { detectHostTimezone } from '../host-timezone.ts';
 
 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 >>>';
@@ -1286,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')
@@ -1364,6 +1373,8 @@ export async function create(args: string[]): Promise<void> {
             const dotfilesMount = dotfilesSnapshot
               ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
               : [];
+            const hostTz = detectHostTimezone();
+            const tzFlags = hostTz ? ['-e', `TZ=${hostTz}`] : [];
 
             runEngineTaskCommand(engine, 'docker', [
               'run',
@@ -1398,6 +1409,7 @@ export async function create(args: string[]): Promise<void> {
               ...liveMountVolumes,
               ...shellConfigVolumes,
               ...envFile.dockerArgs,
+              ...tzFlags,
               '-w',
               '/workspace',
               effectiveConfig.imageName