@fitlab-ai/agent-infra 0.6.2 → 0.6.3

package/README.md

@@ -18,10 +18,13 @@
   <a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-brightgreen?logo=node.js" alt="Node.js >= 22"></a>
   <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
+  <a href="https://codecov.io/gh/fitlab-ai/agent-infra"><img src="https://codecov.io/gh/fitlab-ai/agent-infra/graph/badge.svg" alt="codecov"></a>
   <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
 </p>
 
-[中文版](README.zh-CN.md)
+<p align="center">
+  <strong>English</strong> · <a href="./README.zh-CN.md">中文</a>
+</p>
 
 <a id="why-agent-infra"></a>
 
@@ -201,6 +204,8 @@ The sandbox image also preinstalls `gh`. When `gh auth token` succeeds on the ho
 
 `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.
+
 `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.
 
 ### Host-sandbox file exchange
@@ -212,11 +217,16 @@ the host and the sandbox without polluting the git worktree:
   sandbox of the same project, regardless of branch.
 - `/share/branch` <- `~/.agent-infra/share/<project>/branches/<branch>/` -
   exclusive to the current branch sandbox.
+- `/clipboard` <- `~/.agent-infra/clipboard/` - read-only image paste bridge
+  storage on macOS.
 
 These paths are intentionally hardcoded; there is no `.airc.json` knob. Both
 host directories are created automatically on first `create`. When you
 `ai sandbox rm <branch>` or `ai sandbox rm --all`, you will be prompted (default
 yes) to clean up the corresponding share dirs alongside the worktrees.
+Use `ai sandbox prune --dry-run` to inspect orphaned per-branch state dirs left
+behind by older versions or interrupted cleanup, then `ai sandbox prune` to
+remove only dirs without an active sandbox container.
 Existing sandboxes pick up these mounts after `ai sandbox rm <branch>` and
 `ai sandbox create <branch>`.
 
@@ -452,7 +462,7 @@ These configurations are not actively tested in this release:
 
 - **Podman** instead of Docker: Works on Fedora 40+ and other `dnf`-based RHEL family distros (RHEL, CentOS Stream, Rocky, Alma) via the `podman-docker` shim (`sudo dnf install podman podman-docker`; optionally `sudo touch /etc/containers/nodocker` to silence its per-command notice).
 - **SELinux-enforcing** hosts (Fedora / RHEL): `ai sandbox create` automatically labels bind mounts with Docker's shared `:z` flag — no setup required. Set `AGENT_INFRA_SELINUX_DISABLE=1` to opt out for debugging.
-- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox refresh`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm` directly.
+- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox refresh`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm`, and `ai sandbox prune` directly.
 
 ### Windows
 
@@ -777,7 +787,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.2",
+  "templateVersion": "v0.6.3",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/README.zh-CN.md

@@ -18,10 +18,13 @@
   <a href="License.txt"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-brightgreen?logo=node.js" alt="Node.js >= 22"></a>
   <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
+  <a href="https://codecov.io/gh/fitlab-ai/agent-infra"><img src="https://codecov.io/gh/fitlab-ai/agent-infra/graph/badge.svg" alt="codecov"></a>
   <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
 </p>
 
-[English](README.md)
+<p align="center">
+  <a href="./README.md">English</a> · <strong>中文</strong>
+</p>
 
 <a id="why-agent-infra"></a>
 
@@ -201,6 +204,8 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 `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 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。
+
 `ai sandbox exec` 和 `ai sandbox refresh` 会在宿主机凭证存储与 `~/.agent-infra/credentials/*` 下的所有沙箱项目副本之间做双向 reconcile。长时间运行的沙箱如果先刷新了 OAuth token，下一次进入或刷新命令会把最新有效副本回写到宿主 Keychain 或 `~/.claude/.credentials.json`；宿主机更新时也会继续覆盖项目副本。如果所有副本都已失效，`ai sandbox refresh` 会尝试 `claude /status` 探活，只有探活无法恢复时才提示重新登录。
 
 ### 宿主-沙箱文件交换
@@ -209,8 +214,10 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 - `/share/common` <- `~/.agent-infra/share/<project>/common/`：项目级共享，跨分支可见。
 - `/share/branch` <- `~/.agent-infra/share/<project>/branches/<branch>/`：分支独占。
+- `/clipboard` <- `~/.agent-infra/clipboard/`：macOS 图片粘贴桥接使用的只读存储。
 
 这两条路径硬编码，不暴露 `.airc.json` 配置项。首次 `create` 时会自动创建宿主目录；`ai sandbox rm <branch>` 与 `ai sandbox rm --all` 删除时会附带询问是否清理（默认 yes）。
+可先用 `ai sandbox prune --dry-run` 查看旧版本或异常中断遗留的孤儿 per-branch 状态目录，再用 `ai sandbox prune` 只删除没有活跃 sandbox 容器对应的目录。
 已有沙箱需要执行 `ai sandbox rm <branch>` 后再执行 `ai sandbox create <branch>`，才能加载新的挂载点。
 
 #### 用户级 dotfiles 通道
@@ -428,7 +435,7 @@ Rootless 模式的已知差异：
 
 - 用 **Podman** 替代 Docker：Fedora 40+ 及其他 `dnf` 系 RHEL 发行版（RHEL、CentOS Stream、Rocky、Alma）上通过 `podman-docker` shim 已可使用（`sudo dnf install podman podman-docker`；可选 `sudo touch /etc/containers/nodocker` 抑制 podman 在每条命令前打印的提示）。
 - **SELinux enforcing** 宿主机（Fedora / RHEL）：`ai sandbox create` 会自动给 bind mount 加 Docker 共享 `:z` 标签，无需手动准备。如需排障可设 `AGENT_INFRA_SELINUX_DISABLE=1` 关闭。
-- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox refresh`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`。
+- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox refresh`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`、`ai sandbox prune`。
 
 ### Windows
 
@@ -753,7 +760,7 @@ import-issue #42                    从 GitHub Issue 导入任务
   "project": "my-project",
   "org": "my-org",
   "language": "en",
-  "templateVersion": "v0.6.2",
+  "templateVersion": "v0.6.3",
   "templates": {
     "sources": [
       { "type": "local", "path": "~/private-templates" }

package/bin/cli.ts

@@ -10,7 +10,7 @@ if (major < 22) {
   process.exit(1);
 }
 
-const USAGE = `agent-infra - bootstrap AI collaboration infrastructure
+const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
 Usage:
   agent-infra init        Initialize a new project with update-agent-infra seed command
@@ -104,6 +104,11 @@ switch (command) {
     }
     break;
   }
+  case '--version':
+  case '-v': {
+    console.log(`agent-infra ${VERSION}`);
+    break;
+  }
   case 'help':
   case '':
     process.stdout.write(USAGE);

package/dist/bin/cli.js

@@ -14,7 +14,7 @@ if (major < 22) {
     process.stderr.write(`agent-infra requires Node.js >= 22 (current: ${process.version})\n`);
     process.exit(1);
 }
-const USAGE = `agent-infra - bootstrap AI collaboration infrastructure
+const USAGE = `agent-infra ${VERSION} - bootstrap AI collaboration infrastructure
 
 Usage:
   agent-infra init        Initialize a new project with update-agent-infra seed command
@@ -108,6 +108,11 @@ switch (command) {
         }
         break;
     }
+    case '--version':
+    case '-v': {
+        console.log(`agent-infra ${VERSION}`);
+        break;
+    }
     case 'help':
     case '':
         process.stdout.write(USAGE);

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

@@ -0,0 +1,216 @@
+import { StringDecoder } from 'node:string_decoder';
+import { createClipboardAdapter } from "./index.js";
+import { buildBracketedPaste, CtrlVDetector } from "./keys.js";
+import { clipboardHostDir, containerClipboardPath, pngClipboardFilename, pruneClipboardDir, writeClipboardPngAtomic } from "./paths.js";
+import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from "../shell.js";
+import { loadNodePty } from "./node-pty.js";
+const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
+const PARTIAL_ESCAPE_FLUSH_MS = 30;
+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');
+    }
+    const available = adapter.available();
+    if (!available.ok) {
+        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');
+    }
+    const pty = await loadPty();
+    if (!pty) {
+        return fallback('node-pty optional dependency is unavailable');
+    }
+    const command = commandForEngine(engine, 'docker', dockerArgs);
+    let child;
+    try {
+        child = pty.spawn(command.cmd, command.args, {
+            name: env.TERM || 'xterm-256color',
+            cols: stdout.columns || 120,
+            rows: stdout.rows || 40,
+            cwd,
+            env
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : 'unknown error';
+        return fallback(`node-pty spawn failed: ${message}`);
+    }
+    return runBridge({
+        child,
+        home,
+        adapter,
+        writeStderr,
+        stdin,
+        stdout,
+        detector: createDetector()
+    });
+}
+async function runBridge({ child, home, adapter, writeStderr, stdin, stdout, detector }) {
+    let warnedPasteFailure = false;
+    let flushTimer = null;
+    const inputDecoder = new StringDecoder('utf8');
+    const onData = (chunk) => {
+        clearFlushTimer();
+        for (const token of detector.feed(inputDecoder.write(chunk))) {
+            if (token.kind === 'text') {
+                child.write(token.raw);
+            }
+            else {
+                handleCtrlV(token, child);
+            }
+        }
+        if (detector.hasPending()) {
+            flushTimer = setTimeout(() => {
+                flushTimer = null;
+                for (const token of detector.flush()) {
+                    if (token.kind === 'text') {
+                        child.write(token.raw);
+                    }
+                    else {
+                        handleCtrlV(token, child);
+                    }
+                }
+            }, PARTIAL_ESCAPE_FLUSH_MS);
+        }
+    };
+    const onResize = () => child.resize(stdout.columns || 120, stdout.rows || 40);
+    const onSigint = () => child.kill('SIGINT');
+    const onSigterm = () => child.kill('SIGTERM');
+    function handleCtrlV(match, target) {
+        try {
+            if (!adapter.hasImage()) {
+                target.write(match.raw);
+                return;
+            }
+            const png = adapter.readImagePng();
+            if (!png) {
+                throw new Error('clipboard image could not be read');
+            }
+            const filename = pngClipboardFilename(png);
+            writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
+            pruneClipboardDir(clipboardHostDir(home));
+            target.write(buildBracketedPaste(containerClipboardPath(filename)));
+        }
+        catch (error) {
+            target.write(match.raw);
+            if (!warnedPasteFailure) {
+                warnedPasteFailure = true;
+                writeStderr(`Warning: clipboard image paste failed; forwarded original Ctrl+V (${error instanceof Error ? error.message : 'unknown error'})\n`);
+            }
+        }
+    }
+    function clearFlushTimer() {
+        if (flushTimer) {
+            clearTimeout(flushTimer);
+            flushTimer = null;
+        }
+    }
+    try {
+        stdin.setRawMode?.(true);
+        stdin.resume();
+        stdin.on('data', onData);
+        stdout.on('resize', onResize);
+        process.on('SIGINT', onSigint);
+        process.on('SIGTERM', onSigterm);
+        child.onData((data) => stdout.write(data));
+        return exitCode(await onceExit(child, stdin));
+    }
+    finally {
+        clearFlushTimer();
+        // The child pty is already exiting here; flushing buffered input is
+        // best-effort and must never block terminal/stdin cleanup below.
+        try {
+            for (const token of detector.feed(inputDecoder.end())) {
+                if (token.kind === 'text') {
+                    child.write(token.raw);
+                }
+                else {
+                    handleCtrlV(token, child);
+                }
+            }
+            for (const token of detector.flush()) {
+                if (token.kind === 'text') {
+                    child.write(token.raw);
+                }
+            }
+        }
+        catch {
+            // Writing to an already-closed pty can throw; ignore on teardown.
+        }
+        stdin.off('data', onData);
+        stdout.off('resize', onResize);
+        process.off('SIGINT', onSigint);
+        process.off('SIGTERM', onSigterm);
+        stdin.setRawMode?.(false);
+        // Release stdin so the resumed TTY handle stops keeping the event loop
+        // alive; without this the CLI hangs after the sandbox exits until Ctrl+C.
+        stdin.pause?.();
+        restoreTerminal();
+    }
+}
+function onceExit(child, stdin) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (event) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            stdin.off('end', onStdinEnd);
+            stdin.off('close', onStdinEnd);
+            resolve(event);
+        };
+        const onStdinEnd = () => {
+            child.kill('SIGHUP');
+            finish({ exitCode: 0, signal: 'SIGHUP' });
+        };
+        child.onExit(finish);
+        stdin.once('end', onStdinEnd);
+        stdin.once('close', onStdinEnd);
+    });
+}
+function exitCode(event) {
+    if (event.signal !== undefined && event.signal !== null) {
+        return signalExitCode(event.signal);
+    }
+    if (event.exitCode !== undefined && event.exitCode !== null) {
+        return event.exitCode;
+    }
+    return 1;
+}
+function signalExitCode(signal) {
+    if (typeof signal === 'number') {
+        return 128 + signal;
+    }
+    const signals = {
+        SIGHUP: 1,
+        SIGINT: 2,
+        SIGQUIT: 3,
+        SIGILL: 4,
+        SIGTRAP: 5,
+        SIGABRT: 6,
+        SIGBUS: 7,
+        SIGFPE: 8,
+        SIGKILL: 9,
+        SIGUSR1: 10,
+        SIGSEGV: 11,
+        SIGUSR2: 12,
+        SIGPIPE: 13,
+        SIGALRM: 14,
+        SIGTERM: 15
+    };
+    return 128 + (signals[signal] ?? 0);
+}
+//# sourceMappingURL=bridge.js.map

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

@@ -0,0 +1,73 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const HAS_IMAGE_TIMEOUT_MS = 500;
+const READ_IMAGE_TIMEOUT_MS = 5_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export function createDarwinClipboardAdapter({ execFn = execFileSync, mkdtempFn = fs.mkdtempSync, readFileFn = fs.readFileSync, rmFn = fs.rmSync } = {}) {
+    return {
+        available() {
+            try {
+                execFn('osascript', ['-e', 'return "ok"'], { encoding: 'utf8', timeout: HAS_IMAGE_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');
+            try {
+                try {
+                    execFn('osascript', ['-e', pngWriteScript(outputPath)], {
+                        encoding: 'utf8',
+                        timeout: READ_IMAGE_TIMEOUT_MS
+                    });
+                }
+                catch {
+                    execFn('pngpaste', [outputPath], {
+                        encoding: 'utf8',
+                        timeout: READ_IMAGE_TIMEOUT_MS
+                    });
+                }
+                const png = Buffer.from(readFileFn(outputPath));
+                return isPng(png) ? png : null;
+            }
+            catch {
+                return null;
+            }
+            finally {
+                rmFn(tmpDir, { recursive: true, force: true });
+            }
+        }
+    };
+}
+function isPng(buffer) {
+    return buffer.length >= PNG_MAGIC.length && PNG_MAGIC.every((byte, index) => buffer[index] === byte);
+}
+function pngWriteScript(outputPath) {
+    const escapedPath = outputPath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return [
+        'set pngData to the clipboard as «class PNGf»',
+        `set outFile to POSIX file "${escapedPath}"`,
+        'set fileRef to open for access outFile with write permission',
+        'set eof fileRef to 0',
+        'write pngData to fileRef',
+        'close access fileRef'
+    ].join('\n');
+}
+//# sourceMappingURL=darwin.js.map

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

@@ -0,0 +1,9 @@
+import { platform } from 'node:os';
+import { createDarwinClipboardAdapter } from "./darwin.js";
+export function createClipboardAdapter({ platformName = platform() } = {}) {
+    if (platformName !== 'darwin') {
+        return null;
+    }
+    return createDarwinClipboardAdapter();
+}
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,58 @@
+const CTRL_V_SEQUENCES = [
+    { raw: '\x16', label: 'ctrl-v 0x16' },
+    { raw: '\x1b[118;5u', label: 'ctrl-v csi-u ESC[118;5u' },
+    { raw: '\x1b[27;5;118~', label: 'ctrl-v modifyOtherKeys ESC[27;5;118~' }
+];
+export class CtrlVDetector {
+    #pending = '';
+    hasPending() {
+        return this.#pending.length > 0;
+    }
+    feed(raw) {
+        let input = this.#pending + raw;
+        this.#pending = '';
+        const tokens = [];
+        while (input.length > 0) {
+            const match = CTRL_V_SEQUENCES.find((sequence) => input.startsWith(sequence.raw));
+            if (match) {
+                tokens.push({ kind: 'ctrl-v', raw: match.raw, label: match.label });
+                input = input.slice(match.raw.length);
+                continue;
+            }
+            const partial = CTRL_V_SEQUENCES.some((sequence) => sequence.raw.startsWith(input) && input.length < sequence.raw.length);
+            if (partial) {
+                this.#pending = input;
+                break;
+            }
+            const first = input.slice(0, 1);
+            tokens.push({ kind: 'text', raw: first });
+            input = input.slice(first.length);
+        }
+        return coalesceText(tokens);
+    }
+    flush() {
+        if (!this.#pending) {
+            return [];
+        }
+        const raw = this.#pending;
+        this.#pending = '';
+        return [{ kind: 'text', raw }];
+    }
+}
+function coalesceText(tokens) {
+    const result = [];
+    for (const token of tokens) {
+        const previous = result.at(-1);
+        if (token.kind === 'text' && previous?.kind === 'text') {
+            previous.raw += token.raw;
+        }
+        else {
+            result.push(token);
+        }
+    }
+    return result;
+}
+export function buildBracketedPaste(text) {
+    return `\x1b[200~${text}\x1b[201~`;
+}
+//# sourceMappingURL=keys.js.map

package/dist/lib/sandbox/clipboard/node-pty.js

@@ -0,0 +1,13 @@
+import { createRequire } from 'node:module';
+export async function loadNodePty() {
+    try {
+        const require = createRequire(import.meta.url);
+        const mod = require('@lydell/node-pty');
+        const maybeDefault = mod;
+        return maybeDefault.default ?? mod;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=node-pty.js.map

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

@@ -0,0 +1,59 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { hostJoin } from "../engines/wsl2-paths.js";
+export const CONTAINER_CLIPBOARD_MOUNT = '/clipboard';
+const DEFAULT_KEEP = 20;
+const DEFAULT_MAX_AGE_MS = 24 * 60 * 60 * 1000;
+export function clipboardHostDir(home) {
+    return hostJoin(home, '.agent-infra', 'clipboard');
+}
+export function containerClipboardPath(filename) {
+    return path.posix.join(CONTAINER_CLIPBOARD_MOUNT, filename);
+}
+export function pngClipboardFilename(buffer) {
+    return `${crypto.createHash('sha256').update(buffer).digest('hex').slice(0, 16)}.png`;
+}
+export function writeClipboardPngAtomic(dir, filename, buffer) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        fs.chmodSync(dir, 0o700);
+    }
+    catch {
+        // Best effort: existing directories may live on filesystems that ignore chmod.
+    }
+    const target = path.join(dir, filename);
+    const tmp = path.join(dir, `.${filename}.${process.pid}.tmp`);
+    fs.writeFileSync(tmp, buffer);
+    fs.renameSync(tmp, target);
+    return target;
+}
+export function pruneClipboardDir(dir, { keep = DEFAULT_KEEP, maxAgeMs = DEFAULT_MAX_AGE_MS, now = Date.now() } = {}) {
+    if (!fs.existsSync(dir)) {
+        return [];
+    }
+    const entries = fs.readdirSync(dir)
+        .filter((name) => name.endsWith('.png'))
+        .map((name) => {
+        const fullPath = path.join(dir, name);
+        const stat = fs.statSync(fullPath);
+        return { fullPath, mtimeMs: stat.mtimeMs };
+    })
+        .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    const keepSet = new Set(entries.slice(0, keep).map((entry) => entry.fullPath));
+    const removed = [];
+    for (const entry of entries) {
+        if (keepSet.has(entry.fullPath) && now - entry.mtimeMs <= maxAgeMs) {
+            continue;
+        }
+        try {
+            fs.rmSync(entry.fullPath, { force: true });
+            removed.push(entry.fullPath);
+        }
+        catch {
+            // Cleanup is opportunistic; a failed prune should not break paste.
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=paths.js.map

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

@@ -8,13 +8,14 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import * as toml from 'smol-toml';
 import { loadConfig } from "../config.js";
-import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxLabel, sanitizeBranchName, shareBranchDir, shareCommonDir, worktreeDirCandidates } from "../constants.js";
+import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxLabel, shareBranchDir, shareCommonDir, shellConfigDir, worktreeDirCandidates } from "../constants.js";
 import { prepareDockerfile } from "../dockerfile.js";
 import { detectEngine, ensureDocker } from "../engine.js";
 import { commandForEngine, execEngine, run, runEngine, runOk, runOkEngine, runSafe, runSafeEngine, runVerboseEngine } from "../shell.js";
 import { resolveTaskBranch } from "../task-resolver.js";
 import { resolveTools, toolConfigDirCandidates, toolNpmPackagesArg } from "../tools.js";
 import { hostJoin, toEnginePath, volumeArg } from "../engines/wsl2-paths.js";
+import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from "../clipboard/paths.js";
 import { validateSelinuxDisableEnv } from "../engines/selinux.js";
 import { resolveBuildUid } from "../engines/native.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
@@ -70,7 +71,13 @@ function resolveToolDirs(config, tools, branch) {
     });
 }
 export function hostShellConfigDir(home, project, branch) {
-    return hostJoin(home, '.agent-infra', 'config', project, sanitizeBranchName(branch));
+    return shellConfigDir({ shellConfigBase: hostJoin(home, '.agent-infra', 'config', project) }, branch);
+}
+export function buildClipboardVolumeArgs(engine, home) {
+    return [
+        '-v',
+        volumeArg(engine, clipboardHostDir(home), CONTAINER_CLIPBOARD_MOUNT, ':ro')
+    ];
 }
 function runtimeChecks(runtimes) {
     const checks = [];
@@ -1034,6 +1041,7 @@ export async function create(args) {
                         fs.mkdirSync(workspaceDir, { recursive: true });
                         fs.mkdirSync(shareCommon, { recursive: true });
                         fs.mkdirSync(shareBranch, { recursive: true });
+                        fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
                         const dotfilesSnapshot = materializeDotfiles(effectiveConfig.dotfilesDir, dotfilesCacheDir(effectiveConfig.home, effectiveConfig.project));
                         const dotfilesMount = dotfilesSnapshot
                             ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
@@ -1057,6 +1065,7 @@ export async function create(args) {
                             volumeArg(engine, shareCommon, '/share/common'),
                             '-v',
                             volumeArg(engine, shareBranch, '/share/branch'),
+                            ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
                             '-v',
                             volumeArg(engine, path.join(effectiveConfig.repoRoot, '.git'), `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`),
                             '-v',

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

@@ -5,6 +5,7 @@ import { formatCredentialWarnings, formatRemaining, reconcileClaudeCredentials,
 import { runInteractiveEngine, runSafeEngine } from "../shell.js";
 import { resolveTaskBranch } from "../task-resolver.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
+import { runInteractiveWithClipboardBridge } from "../clipboard/bridge.js";
 const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
@@ -51,7 +52,7 @@ export function formatCredentialSyncStatus(result, isTTY = process.stderr.isTTY)
     }
     return null;
 }
-export function enter(args) {
+export async function enter(args) {
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(`${USAGE}\n`);
         if (args.length === 0) {
@@ -91,7 +92,12 @@ export function enter(args) {
         catch (error) {
             process.stderr.write(`Warning: dotfiles snapshot rebuild failed: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
         }
-        return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH]);
+        return runInteractiveWithClipboardBridge({
+            engine,
+            dockerArgs: ['exec', '-it', ...envFlags, container, 'bash', TMUX_ENTRY_PATH],
+            container,
+            home: config.home
+        });
     }
     return runInteractiveEngine(engine, 'docker', ['exec', '-it', ...envFlags, container, ...cmd]);
 }