@fitlab-ai/agent-infra 0.8.3 → 0.8.5

package/README.zh-CN.md

@@ -207,3 +207,13 @@ my-project/
 ## 许可协议
 
 [MIT](License.txt)
+
+## 社区
+
+- 微信公众号：`FitFramework`
+- QQ 技术交流群：`1029802553`
+
+<p align="center">
+  <img src="./assets/qrcode_for_wechat_gh.png" alt="FitFramework 微信公众号二维码" width="250">
+  <img src="./assets/qrcode_for_qq_01.png" alt="FitFramework QQ 技术交流群二维码" width="250">
+</p>

package/bin/cli.ts

@@ -15,7 +15,7 @@ const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructur
 Usage: ai <command> [options]
 
 Commands:
-  cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   decide          Record a human decision for a task HD item
   help            Show this help message
   init            Initialize a new project with update-agent-infra seed command

package/dist/bin/cli.js

@@ -19,7 +19,7 @@ const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructur
 Usage: ai <command> [options]
 
 Commands:
-  cp <ssh-alias>  Copy local clipboard image to a remote macOS NSPasteboard
+  cp <ssh-alias>  Copy local clipboard image to a remote macOS clipboard or Linux sandbox over SSH
   decide          Record a human decision for a task HD item
   help            Show this help message
   init            Initialize a new project with update-agent-infra seed command

package/dist/lib/cp.js

@@ -5,7 +5,8 @@ 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';
+import { RECEIVER_CAPABILITY, receiveRemoteClipboardPng } from './sandbox/clipboard/inbox.js';
+const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS clipboard or Linux sandbox over SSH.\n';
 const COMMAND_TIMEOUT_MS = 30_000;
 export function runCommand(cmd, args, input) {
     const result = spawnSync(cmd, args, {
@@ -23,6 +24,22 @@ export function runCommand(cmd, args, input) {
 }
 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.length === 1 && args[0] === '--remote-receive-capability') {
+        if (platform === 'linux')
+            writeStdout(`${RECEIVER_CAPABILITY}\n`);
+        return platform === 'linux' ? 0 : 1;
+    }
+    if (args.length === 2 && args[0] === '--remote-receive-v1') {
+        try {
+            const result = receiveRemoteClipboardPng(process.env.HOME || process.env.USERPROFILE || '', args[1], platform);
+            writeStdout(`${result}\n`);
+            return 0;
+        }
+        catch (error) {
+            writeStderr(`${error instanceof Error ? error.message : 'clipboard receive failed'}\n`);
+            return 1;
+        }
+    }
     if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
         writeStdout(USAGE);
         return 0;
@@ -62,6 +79,34 @@ export async function cmdCp(args, deps = {}) {
         const localPng = path.join(localTmpDir, 'clipboard.png');
         writeFileFn(localPng, png);
         remotePath = `/tmp/agent-infra-cp-${randomId()}.png`;
+        const remoteSystem = spawnFn('ssh', [
+            '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'uname', '-s'
+        ]);
+        if (remoteSystem.status !== 0) {
+            writeStderr(`failed to detect remote platform on ${alias}:\n${commandDetail(remoteSystem)}\n`);
+            return 1;
+        }
+        const remotePlatform = remoteSystem.stdout.trim();
+        if (remotePlatform !== 'Darwin' && remotePlatform !== 'Linux') {
+            writeStderr(`unsupported remote platform on ${alias}: ${remotePlatform || 'unknown'}\n`);
+            return 1;
+        }
+        if (remotePlatform === 'Linux') {
+            const homeCheck = spawnFn('ssh', [
+                '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'test', '-d', '$HOME/.agent-infra'
+            ]);
+            if (homeCheck.status !== 0) {
+                writeStderr(`remote agent-infra installation is missing on ${alias}\n`);
+                return 1;
+            }
+            const capability = spawnFn('ssh', [
+                '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'ai', 'cp', '--remote-receive-capability'
+            ]);
+            if (capability.status !== 0 || capability.stderr !== '' || capability.stdout.replace(/\n$/u, '') !== RECEIVER_CAPABILITY) {
+                writeStderr(`remote agent-infra clipboard receiver is unavailable or incompatible on ${alias}; update agent-infra\n`);
+                return 1;
+            }
+        }
         const upload = spawnFn('scp', [
             '-o',
             'BatchMode=yes',
@@ -75,24 +120,20 @@ export async function cmdCp(args, deps = {}) {
             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));
+        const setRemote = remotePlatform === 'Darwin'
+            ? spawnFn('ssh', [
+                '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'osascript', '-'
+            ], remoteSetScript(remotePath))
+            : spawnFn('ssh', [
+                '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'ai', 'cp', '--remote-receive-v1', 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`);
+        writeStdout(remotePlatform === 'Linux'
+            ? `uploaded clipboard image to ${alias}; return to the SSH session and press Ctrl+V\n`
+            : `copied clipboard image to ${alias}\n`);
         return 0;
     }
     finally {

package/dist/lib/defaults.json

@@ -44,14 +44,23 @@
       ".gemini/commands/",
       ".git-hooks/check-version-format.sh",
       ".github/scripts/",
+      ".github/workflows/metadata-sync.yml",
+      ".github/workflows/pr-label.yml",
+      ".github/workflows/status-label.yml",
       ".opencode/commands/"
     ],
+    "guardedManaged": [
+      ".github/workflows/metadata-sync.yml",
+      ".github/workflows/pr-label.yml",
+      ".github/workflows/status-label.yml"
+    ],
     "merged": [
       "**/post-release.*",
       "**/release.*",
       "**/test-integration.*",
       "**/test.*",
       "**/upgrade-dependency.*",
+      ".agents/rules/testing-discipline.*",
       ".agents/skills/post-release/SKILL.*",
       ".agents/skills/release/SKILL.*",
       ".agents/skills/test-integration/SKILL.*",

package/dist/lib/init.js

@@ -197,6 +197,8 @@ async function cmdInit() {
     // install skill
     copySkillDir(path.join(templateDir, '.agents', 'skills', 'update-agent-infra'), path.join('.agents', 'skills', 'update-agent-infra'), replacements, language, platformType);
     ok('Installed .agents/skills/update-agent-infra/');
+    renderFile(path.join(templateDir, '.agents', 'scripts', 'lib', 'agent-infra-package.js'), path.join('.agents', 'scripts', 'lib', 'agent-infra-package.js'), replacements);
+    ok('Installed .agents/scripts/lib/agent-infra-package.js');
     // install Claude command (only if enabled)
     if (enabledTUISet.has('claude-code')) {
         renderFile(path.join(templateDir, '.claude', 'commands', claudeSrc), path.join('.claude', 'commands', 'update-agent-infra.md'), replacements);
@@ -245,6 +247,9 @@ async function cmdInit() {
     console.log('');
     ok('Project initialized successfully!');
     console.log('');
+    console.log('  If this init used npx, install agent-infra persistently before update or validation:');
+    console.log('    npm install -g @fitlab-ai/agent-infra');
+    console.log('');
     if (enabledTUISet.size === 0) {
         console.log('  No built-in TUI selected.');
         console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);

package/dist/lib/sandbox/capture.js

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { loadConfig } from './config.js';
 import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.js';
 import { detectEngine } from './engine.js';
+import { commandForEngine } from './shell.js';
 import { hostTimezoneEnvFlags, terminalEnvFlags } from './commands/enter.js';
 import { fetchSandboxRows, selectSandboxContainer, startSandboxContainer } from './commands/list-running.js';
 async function spawnCapture(file, args) {
@@ -49,12 +50,12 @@ function buildRunScript(params) {
     return `#!/bin/sh
 set -u
 cd /workspace
-date "+%Y-%m-%d %H:%M:%S%:z" > ${runDir}/started_at
+date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\\([+-][0-9][0-9]\\)\\([0-9][0-9]\\)$/\\1:\\2/' > ${runDir}/started_at
 printf '%s\\n' running > ${runDir}/status
 ${command}
 code=$?
 printf '%s\\n' "$code" > ${runDir}/exit_code
-date "+%Y-%m-%d %H:%M:%S%:z" > ${runDir}/finished_at
+date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\\([+-][0-9][0-9]\\)\\([0-9][0-9]\\)$/\\1:\\2/' > ${runDir}/finished_at
 if [ "$code" -eq 0 ]; then
   printf '%s\\n' completed > ${runDir}/status
 else
@@ -144,7 +145,8 @@ export async function runInSandbox(request, options = {}) {
         '-lc',
         buildTmuxLauncher({ request, runId })
     ];
-    const result = await (options.spawn ?? spawnCapture)('docker', dockerArgs);
+    const command = commandForEngine(engine, 'docker', dockerArgs);
+    const result = await (options.spawn ?? spawnCapture)(command.cmd, command.args);
     return {
         ...result,
         run: {

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

@@ -3,6 +3,7 @@ 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';
+import { isClipboardInboxReadable, readPendingClipboardPath } from './inbox.js';
 import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from '../shell.js';
 import { loadNodePty } from './node-pty.js';
 const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
@@ -37,13 +38,10 @@ export async function runInteractiveWithClipboardBridge(options) {
     if (!stdin.isTTY || !stdout.isTTY) {
         return fallback('host stdin/stdout is not a TTY');
     }
-    if (!adapter) {
-        return fallback('no clipboard adapter available on this platform');
-    }
-    const available = adapter.available();
-    if (!available.ok) {
+    const available = adapter?.available() ?? { ok: false, reason: 'no clipboard adapter available on this platform' };
+    const inboxReady = isClipboardInboxReadable(home);
+    if (!available.ok && !inboxReady)
         return fallback(available.reason);
-    }
     if (!runOk(engine, 'docker', ['exec', container, 'sh', '-c', '[ -d /clipboard ] && [ -r /clipboard ]'])) {
         return fallback('container /clipboard mount is missing; rebuild the sandbox to enable image paste');
     }
@@ -69,7 +67,7 @@ export async function runInteractiveWithClipboardBridge(options) {
     return runBridge({
         child,
         home,
-        adapter,
+        adapter: available.ok ? adapter : null,
         writeStderr,
         stdin,
         stdout,
@@ -116,7 +114,7 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
     function handleText(raw, target) {
         const textAdapter = adapter;
         const pastedText = extractSinglePathPaste(raw);
-        if (!textAdapter.readImageFromText || pastedText === null) {
+        if (!textAdapter || !textAdapter.readImageFromText || pastedText === null) {
             target.write(raw);
             return;
         }
@@ -138,12 +136,17 @@ async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, det
     }
     function handleCtrlV(match, target) {
         try {
+            const pendingPath = readPendingClipboardPath(home);
+            if (pendingPath) {
+                target.write(buildBracketedPaste(pendingPath));
+                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();
+            const png = adapter?.readImagePng() ?? null;
             if (!png) {
                 target.write(match.raw);
                 return;

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

@@ -0,0 +1,82 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { clipboardHostDir, containerClipboardPath, pngClipboardFilename, pruneClipboardDir, writeClipboardPngAtomic } from './paths.js';
+export const RECEIVER_CAPABILITY = 'AGENT_INFRA_CLIPBOARD_RECEIVER:v1';
+const MARKER = '.pending.json';
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const HASHED_PNG = /^[a-f0-9]{16}\.png$/u;
+const REMOTE_TEMP = /^agent-infra-cp-[0-9a-f-]{36}\.png$/u;
+export function isClipboardInboxReadable(home) {
+    const dir = clipboardHostDir(home);
+    try {
+        fs.accessSync(dir, fs.constants.R_OK);
+        return fs.statSync(dir).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function receiveRemoteClipboardPng(home, tempPath, platformName = process.platform) {
+    if (platformName !== 'linux')
+        throw new Error('remote clipboard receiver requires Linux');
+    if (path.dirname(tempPath) !== '/tmp' || !REMOTE_TEMP.test(path.basename(tempPath))) {
+        throw new Error('invalid clipboard upload path');
+    }
+    const signature = Buffer.alloc(PNG_SIGNATURE.length);
+    const fd = fs.openSync(tempPath, 'r');
+    let signatureBytes;
+    try {
+        signatureBytes = fs.readSync(fd, signature, 0, signature.length, 0);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    if (signatureBytes !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE)) {
+        throw new Error('uploaded clipboard file is not a PNG');
+    }
+    const png = fs.readFileSync(tempPath);
+    const dir = clipboardHostDir(home);
+    if (!fs.existsSync(path.dirname(dir)))
+        throw new Error('agent-infra is not installed on this host');
+    const filename = pngClipboardFilename(png);
+    writeClipboardPngAtomic(dir, filename, png);
+    pruneClipboardDir(dir);
+    const markerTmp = path.join(dir, `.${MARKER}.${process.pid}.tmp`);
+    fs.writeFileSync(markerTmp, JSON.stringify({ version: 1, filename, createdAt: new Date().toISOString() }) + '\n', { mode: 0o600 });
+    fs.renameSync(markerTmp, path.join(dir, MARKER));
+    return containerClipboardPath(filename);
+}
+export function readPendingClipboardPath(home) {
+    const dir = clipboardHostDir(home);
+    const markerPath = path.join(dir, MARKER);
+    let markerText;
+    try {
+        markerText = fs.readFileSync(markerPath, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new Error('invalid clipboard pending marker', { cause: error });
+    }
+    let marker;
+    try {
+        marker = JSON.parse(markerText);
+    }
+    catch (error) {
+        throw new Error('invalid clipboard pending marker', { cause: error });
+    }
+    if (marker.version !== 1 || typeof marker.filename !== 'string' || !HASHED_PNG.test(marker.filename)) {
+        throw new Error('invalid clipboard pending marker');
+    }
+    const filePath = path.join(dir, marker.filename);
+    try {
+        const stat = fs.lstatSync(filePath);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error('pending clipboard image is not a regular file');
+    }
+    catch (error) {
+        throw new Error('invalid clipboard pending marker', { cause: error });
+    }
+    return containerClipboardPath(marker.filename);
+}
+//# sourceMappingURL=inbox.js.map

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

@@ -47,13 +47,27 @@ alias gy='gemini --yolo; tput ed'
 `;
 const CONTAINER_HOME = '/home/devuser';
 const CONTAINER_SHELL_CONFIG_MOUNT = `${CONTAINER_HOME}/.host-shell-config`;
-const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh]
+const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh] [--inherit-proxy|-P]
 
 Host aliases:
   ${'~'}/.agent-infra/aliases/sandbox.sh is auto-created on first run and exposed
   as ${CONTAINER_HOME}/.bash_aliases inside the sandbox container (the host
   shell-config directory is bind-mounted at ${CONTAINER_SHELL_CONFIG_MOUNT} and
-  symlinked into $HOME).`;
+  symlinked into $HOME).
+
+Proxy:
+  --inherit-proxy, -P  Copy non-empty standard host proxy variables into the
+                       container environment through the private env file.`;
+const HOST_PROXY_ENV_KEYS = [
+    'http_proxy',
+    'HTTP_PROXY',
+    'https_proxy',
+    'HTTPS_PROXY',
+    'all_proxy',
+    'ALL_PROXY',
+    'no_proxy',
+    'NO_PROXY'
+];
 function resolveToolDirs(config, tools, branch) {
     return tools.map((tool) => {
         const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -209,12 +223,14 @@ export function writeSanitizedGitconfig({ home, hostConfigDir, stripGpg, repoRoo
 // Keep in sync with the symlink block in lib/sandbox/runtimes/ai-tools.dockerfile.
 const SHELL_CONFIG_SYMLINKS = ['.gitconfig', '.gitignore_global', '.stCommitMsg', '.bash_aliases'];
 export function ensureShellConfigSymlinks(engine, container, execFn = execEngine) {
-    // Idempotent symlink setup. Runs against a started container so it also
-    // covers custom Dockerfiles that don't bake the symlinks into the image.
-    const script = SHELL_CONFIG_SYMLINKS
-        .map((file) => `ln -sf .host-shell-config/${file} ${CONTAINER_HOME}/${file}`)
-        .join(' && ');
-    execFn(engine, 'docker', ['exec', container, 'bash', '-lc', script], { stdio: 'ignore' });
+    // Idempotent symlink setup. Avoid a shell command here because Windows .cmd
+    // engine shims would interpret metacharacters in a `bash -lc` script before
+    // forwarding it to Docker.
+    for (const file of SHELL_CONFIG_SYMLINKS) {
+        execFn(engine, 'docker', [
+            'exec', container, 'ln', '-sf', `.host-shell-config/${file}`, `${CONTAINER_HOME}/${file}`
+        ], { stdio: 'ignore' });
+    }
 }
 export function prepareHostShellConfig({ home, project, branch, repoRoot }) {
     const hostDir = hostShellConfigDir(home, project, branch);
@@ -423,10 +439,21 @@ function formatEnvFileEntry(key, value) {
     }
     return `${key}=${value}`;
 }
+export function collectHostProxyEntries(env) {
+    const entriesByExactKey = new Map(Object.entries(env));
+    return HOST_PROXY_ENV_KEYS.flatMap((key) => {
+        const value = entriesByExactKey.get(key);
+        return typeof value === 'string' && value !== '' ? [[key, value]] : [];
+    });
+}
 export function buildContainerEnvFile(resolvedTools, engine, runSafeEngineFn = runSafeEngine, options = {}) {
-    const { mkdtempFn = fs.mkdtempSync, writeFileFn = fs.writeFileSync, chmodFn = fs.chmodSync, rmFn = fs.rmSync, tmpDir = os.tmpdir() } = options;
+    const { additionalEntries = [], mkdtempFn = fs.mkdtempSync, writeFileFn = fs.writeFileSync, chmodFn = fs.chmodSync, rmFn = fs.rmSync, tmpDir = os.tmpdir(), runSafeFn = runSafe } = options;
     const entries = resolvedTools.flatMap(({ tool }) => Object.entries(tool.envVars ?? {}));
-    const ghToken = runSafeEngineFn(engine, 'gh', ['auth', 'token']);
+    entries.push(...additionalEntries);
+    let ghToken = runSafeEngineFn(engine, 'gh', ['auth', 'token']);
+    if (!ghToken && engine === 'wsl2') {
+        ghToken = runSafeFn('gh', ['auth', 'token']);
+    }
     if (ghToken) {
         entries.push(['GH_TOKEN', ghToken]);
     }
@@ -928,6 +955,7 @@ export async function create(args) {
             cpu: { type: 'string' },
             memory: { type: 'string' },
             'no-refresh': { type: 'boolean' },
+            'inherit-proxy': { type: 'boolean', short: 'P' },
             help: { type: 'boolean', short: 'h' }
         }
     });
@@ -1143,8 +1171,12 @@ export async function create(args) {
                     const cachedGpg = needsGpg
                         ? readGpgCache(effectiveConfig.home, effectiveConfig.project, undefined, signingKey)
                         : null;
-                    const envFile = buildContainerEnvFile(effectiveResolvedTools, engine);
+                    const proxyEntries = values['inherit-proxy'] ? collectHostProxyEntries(process.env) : [];
+                    const envFile = buildContainerEnvFile(effectiveResolvedTools, engine, undefined, {
+                        additionalEntries: proxyEntries
+                    });
                     let hostShellConfig;
+                    let tmpfsSeedPlan = [];
                     try {
                         const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
                         if (claudeCodeEntry) {
@@ -1181,21 +1213,23 @@ export async function create(args) {
                             '-v',
                             volumeArg(engine, hostPath, containerPath, ':ro')
                         ]);
-                        // A tmpfs containerMount starts empty, so the config seeded into the
-                        // host dir before launch would be invisible in-container. Bind only
-                        // the explicitly declared seed entries (config.toml, model-catalogs)
-                        // back over the tmpfs as nested mounts — the same proven mechanism as
-                        // hostLiveMounts/auth.json, established at `docker run` time (no
-                        // post-start `docker cp`, which can land under a freshly-mounted
-                        // tmpfs instead of inside it). The allowlist is deliberate: any
-                        // runtime files left in the host dir (e.g. a stale logs_2.sqlite or
-                        // sessions/ from a previous bind-mount era) must NOT be re-mounted,
-                        // or the high-churn writes would land on the host SSD again.
-                        const tmpfsSeedVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => (tool.tmpfs?.seed ?? []).flatMap((entry) => {
+                        // Mount each declared seed read-only at an isolated staging path.
+                        // After docker run mounts the empty tmpfs, the container's default
+                        // user copies these entries into it so the runtime targets are normal,
+                        // writable files rather than nested mount points. The allowlist keeps
+                        // stale runtime files (logs_2.sqlite, sessions, etc.) on the host from
+                        // being exposed or written through.
+                        tmpfsSeedPlan = effectiveResolvedTools.flatMap(({ tool, dir }) => (tool.tmpfs?.seed ?? []).flatMap((entry, index) => {
                             const hostPath = path.join(dir, entry);
-                            return fs.existsSync(hostPath)
-                                ? ['-v', volumeArg(engine, hostPath, path.posix.join(tool.containerMount, entry))]
-                                : [];
+                            if (!fs.existsSync(hostPath)) {
+                                return [];
+                            }
+                            const stagingPath = path.posix.join('/run/agent-infra/tmpfs-seeds', tool.id, String(index));
+                            return [{
+                                    stagingPath,
+                                    targetPath: path.posix.join(tool.containerMount, entry),
+                                    volumeArgs: ['-v', volumeArg(engine, hostPath, stagingPath, ':ro')]
+                                }];
                         }));
                         const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
                             .filter(({ hostPath }) => fs.existsSync(hostPath))
@@ -1238,7 +1272,7 @@ export async function create(args) {
                             ...dotfilesMount,
                             ...toolVolumes,
                             ...tmpfsArgs,
-                            ...tmpfsSeedVolumes,
+                            ...tmpfsSeedPlan.flatMap(({ volumeArgs }) => volumeArgs),
                             ...liveMountVolumes,
                             ...shellConfigVolumes,
                             ...envFile.dockerArgs,
@@ -1251,6 +1285,14 @@ export async function create(args) {
                     finally {
                         envFile.cleanup();
                     }
+                    for (const { stagingPath, targetPath } of tmpfsSeedPlan) {
+                        runEngineTaskCommand(engine, 'docker', [
+                            'exec', container, 'mkdir', '-p', path.posix.dirname(targetPath)
+                        ]);
+                        runEngineTaskCommand(engine, 'docker', [
+                            'exec', container, 'cp', '-R', '--', stagingPath, targetPath
+                        ]);
+                    }
                     // Belt-and-suspenders: re-create the four shell-config symlinks at
                     // runtime so users with a custom `sandbox.dockerfile` (which won't
                     // include the ai-tools.dockerfile symlink fragment) still get

package/dist/lib/sandbox/engine.js

@@ -1,7 +1,7 @@
 import { platform } from 'node:os';
 import { detectHostResources } from './constants.js';
 import { ADAPTERS, enginesForPlatform, getAdapter } from './engines/index.js';
-import { run, runOk, runSafe, runVerbose } from './shell.js';
+import { run, runOk, runOkEngine, runSafe, runVerbose } from './shell.js';
 export const ENGINES = Object.freeze({
     COLIMA: 'colima',
     ORBSTACK: 'orbstack',
@@ -27,6 +27,34 @@ function applyDockerContext(adapter) {
         process.env.DOCKER_CONTEXT = adapter.dockerContext;
     }
 }
+function buildKitError(engine) {
+    let repair;
+    switch (engine) {
+        case ENGINES.COLIMA:
+            repair = 'Install the Docker Buildx plugin with: brew install docker-buildx';
+            break;
+        case ENGINES.DOCKER_DESKTOP:
+        case ENGINES.WSL2:
+            repair = 'Upgrade or repair Docker Desktop so Docker Buildx and BuildKit are available.';
+            break;
+        case ENGINES.NATIVE:
+            repair = 'Install the Docker Buildx plugin for your Docker Engine installation.';
+            break;
+        default:
+            repair = `Upgrade or repair ${engineDisplayName(engine)} so Docker Buildx and BuildKit are available.`;
+    }
+    return new Error([
+        `Docker BuildKit is not available for ${engineDisplayName(engine)}.`,
+        repair,
+        'Verify the builder with: docker buildx inspect --bootstrap',
+        'Then retry the sandbox create or rebuild command.'
+    ].join('\n'));
+}
+function ensureBuildKit(engine, runOkEngineFn) {
+    if (!runOkEngineFn(engine, 'docker', ['buildx', 'inspect', '--bootstrap'])) {
+        throw buildKitError(engine);
+    }
+}
 export function validateSandboxEngine(engine, { platformFn = platform } = {}) {
     if (engine === null || engine === undefined) {
         return null;
@@ -90,9 +118,11 @@ export async function ensureDocker(config, onMessage, dependencies = {}) {
     const engine = detectEngine(config, dependencies);
     const adapter = getAdapter(engine);
     const effectiveConfig = effectiveConfigFor(adapter, config);
+    const fns = runFns(dependencies);
     applyDockerContext(adapter);
-    const vmJustStarted = await adapter.ensure(effectiveConfig, onMessage, runFns(dependencies));
-    adapter.syncResources(effectiveConfig, onMessage, runFns(dependencies), { vmJustStarted });
+    const vmJustStarted = await adapter.ensure(effectiveConfig, onMessage, fns);
+    ensureBuildKit(engine, dependencies.runOkEngineFn ?? runOkEngine);
+    adapter.syncResources(effectiveConfig, onMessage, fns, { vmJustStarted });
 }
 export function isVmManaged(config = {}, dependencies = {}) {
     try {

package/dist/lib/sandbox/engines/colima.js

@@ -28,8 +28,8 @@ export const colimaAdapter = {
     async ensure(config, onMessage, { runOk, runSafe, runVerbose }) {
         let started = false;
         if (!runOk('which', ['colima'])) {
-            onMessage?.('Installing colima + docker via Homebrew...');
-            runVerbose('brew', ['install', 'colima', 'docker']);
+            onMessage?.('Installing colima + docker + docker-buildx via Homebrew...');
+            runVerbose('brew', ['install', 'colima', 'docker', 'docker-buildx']);
         }
         if (!runOk('colima', ['status'])) {
             onMessage?.('Starting Colima VM...');

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

@@ -12,6 +12,9 @@ RUN if [ "${HOST_UID}" = "0" ]; then \
         (groupadd -o -g ${HOST_GID} devuser || true) && \
         useradd -o -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser; \
     else \
+        if ubuntu_uid="$(id -u ubuntu 2>/dev/null)" && [ "${ubuntu_uid}" = "${HOST_UID}" ]; then \
+            userdel -r ubuntu || exit 1; \
+        fi; \
         (groupadd -g ${HOST_GID} devuser || true) && \
         useradd -u ${HOST_UID} -g ${HOST_GID} -m -s /bin/bash devuser; \
     fi
@@ -188,6 +191,10 @@ fi
 exec tmux new-session -s "$SESSION"
 SCRIPT
 
+RUN test -s /usr/local/bin/cc-token-status && test -x /usr/local/bin/cc-token-status && \
+    test -s /usr/local/bin/sandbox-dotfiles-link && test -x /usr/local/bin/sandbox-dotfiles-link && \
+    test -s /usr/local/bin/sandbox-tmux-entry && test -x /usr/local/bin/sandbox-tmux-entry
+
 ENV LANG=en_US.UTF-8
 ENV LC_ALL=en_US.UTF-8
 ENV TERM=xterm-256color

package/dist/lib/sandbox/shell.js

@@ -1,6 +1,7 @@
 import { execFileSync, spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
+import { getAdapter } from './engines/index.js';
 const DEFAULT_TIMEOUT_MS = 60 * 60 * 1000;
 function normalizeOptions(opts = {}, stdio) {
     return {
@@ -114,6 +115,12 @@ export function commandForEngine(engine, cmd, args = []) {
         const resolvedWrapper = resolveCommand('wsl.exe');
         return { cmd: resolvedWrapper, args: ['--', cmd, ...args] };
     }
+    if (cmd === 'docker') {
+        const context = getAdapter(engine).dockerContext;
+        if (context) {
+            return { cmd, args: ['--context', context, ...args] };
+        }
+    }
     return { cmd, args };
 }
 export function runEngine(engine, cmd, args, opts = {}) {
@@ -122,7 +129,8 @@ export function runEngine(engine, cmd, args, opts = {}) {
 }
 export function execEngine(engine, cmd, args, opts = {}) {
     const command = commandForEngine(engine, cmd, args);
-    return execFileSync(command.cmd, command.args, opts);
+    const resolved = resolveCommand(command.cmd);
+    return execFileSync(resolved, command.args, commandOptions(resolved, opts));
 }
 export function runOkEngine(engine, cmd, args, opts = {}) {
     const command = commandForEngine(engine, cmd, args);