@fitlab-ai/agent-infra 0.6.4 → 0.7.0

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/defaults.json

@@ -2,6 +2,7 @@
   "platform": {
     "type": "github"
   },
+  "requiresPullRequest": true,
   "sandbox": {
     "engine": null,
     "runtimes": [

package/dist/lib/init.js

@@ -156,6 +156,8 @@ async function cmdInit() {
         info(`Custom platform '${platformType}' selected. Built-in templates are only complete for github;`
             + ` provide matching '.${platformType}.' or generic templates before running update-agent-infra.`);
     }
+    const requiresPRChoice = await select('Require Pull Request flow?', ['yes', 'no'], 'yes');
+    const requiresPullRequest = requiresPRChoice !== 'no';
     const templateSources = parseLocalSources(await prompt('Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)', ''));
     const skillSources = parseLocalSources(await prompt('Skill sources (optional, comma-separated local paths, e.g. ~/my-skills; Enter to skip)', ''));
     closePrompt();
@@ -199,6 +201,7 @@ async function cmdInit() {
         org: orgName,
         language,
         platform: { type: platformType },
+        requiresPullRequest,
         templateVersion: VERSION,
         sandbox: structuredClone(defaults.sandbox),
         labels: structuredClone(defaults.labels),

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

@@ -13,12 +13,13 @@ 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 { imageSignatureFields, resolveTools, toolConfigDirCandidates, toolNpmPackagesArg, toolShellInstallScriptBase64 } 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";
+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"}';
@@ -57,7 +58,7 @@ function buildSignature(preparedDockerfile, tools) {
     return createHash('sha256')
         .update(JSON.stringify({
         dockerfile: preparedDockerfile.signature,
-        tools: tools.map((tool) => tool.npmPackage)
+        tools: imageSignatureFields(tools)
     }))
         .digest('hex')
         .slice(0, 12);
@@ -788,6 +789,8 @@ export function buildImage(config, tools, dockerfilePath, imageSignature, { engi
         `HOST_GID=${hostGid}`,
         '--build-arg',
         `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+        '--build-arg',
+        `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
         '--label',
         sandboxLabel(config),
         '--label',
@@ -981,6 +984,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

@@ -1,5 +1,5 @@
 import { loadConfig } from "../config.js";
-import { assertValidBranchName, containerNameCandidates } from "../constants.js";
+import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from "../constants.js";
 import { detectEngine } from "../engine.js";
 import { formatCredentialWarnings, formatRemaining, reconcileClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
 import { runInteractiveEngine, runSafeEngine } from "../shell.js";
@@ -7,7 +7,11 @@ import { resolveTaskBranch } from "../task-resolver.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
 import { runInteractiveWithClipboardBridge } from "../clipboard/bridge.js";
 import { detectHostTimezone } from "../host-timezone.js";
-const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
+import { fetchSandboxRows, isTaskShortRef, resolveTaskShortRef } from "./list-running.js";
+const USAGE = `Usage: ai sandbox exec <branch | TASK-id | '#N'> [cmd...]
+
+'#N' references the N-th running sandbox in 'ai sandbox ls' order (1-based).
+Quote it as '#N' to avoid shell '#' comment handling.`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
 // inspect to enable progressive enhancements such as the kitty keyboard
@@ -34,6 +38,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';
@@ -68,8 +83,15 @@ export async function enter(args) {
     const config = loadConfig();
     validateClaudeCredentialsEnvOverride();
     const engine = detectEngine(config);
-    const [branchOrTaskId = '', ...cmd] = args;
-    const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
+    const [firstArg = '', ...cmd] = args;
+    let branch;
+    if (isTaskShortRef(firstArg)) {
+        const { running } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+        branch = resolveTaskShortRef(firstArg, { running });
+    }
+    else {
+        branch = resolveTaskBranch(firstArg, config.repoRoot);
+    }
     assertValidBranchName(branch);
     const running = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
     const container = containerNameCandidates(config, branch).find((name) => running.includes(name));
@@ -97,9 +119,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/list-running.js

@@ -0,0 +1,108 @@
+import { runSafeEngine } from "../shell.js";
+export function containerListFormat() {
+    return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
+}
+export function parseLabels(csv) {
+    if (!csv) {
+        return {};
+    }
+    const labels = {};
+    for (const pair of csv.split(',')) {
+        if (!pair) {
+            continue;
+        }
+        const eq = pair.indexOf('=');
+        if (eq < 0) {
+            continue;
+        }
+        labels[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return labels;
+}
+export function parseSandboxRows(rawOutput, branchKey) {
+    if (!rawOutput) {
+        return [];
+    }
+    return rawOutput.split('\n').map((line) => {
+        const [name = '', status = '', labelsCsv = ''] = line.split('\t');
+        const branch = parseLabels(labelsCsv)[branchKey] ?? '';
+        return {
+            name,
+            status,
+            branch,
+            running: status.startsWith('Up '),
+            index: null
+        };
+    });
+}
+export function sortAndIndexSandboxRows(rows) {
+    const byName = (a, b) => {
+        if (a.name < b.name)
+            return -1;
+        if (a.name > b.name)
+            return 1;
+        return 0;
+    };
+    const running = rows.filter((row) => row.running).sort(byName).map((row, i) => ({
+        ...row,
+        index: i + 1
+    }));
+    const nonRunning = rows.filter((row) => !row.running).sort(byName).map((row) => ({
+        ...row,
+        index: null
+    }));
+    return { running, nonRunning };
+}
+export function fetchSandboxRows(engine, label, branchKey) {
+    const raw = runSafeEngine(engine, 'docker', [
+        'ps',
+        '-a',
+        '--filter',
+        `label=${label}`,
+        '--format',
+        containerListFormat()
+    ]);
+    return sortAndIndexSandboxRows(parseSandboxRows(raw, branchKey));
+}
+/**
+ * Returns true iff `arg` is a syntactically valid task short reference ('#N').
+ * Zero IO. Callers MUST use this as the gate before constructing any context
+ * for resolveTaskShortRef — that way non-matching arguments (e.g. '#abc',
+ * '#1.5', '#') never trigger sandbox list IO.
+ */
+export function isTaskShortRef(arg) {
+    return /^#\d+$/.test(arg);
+}
+/**
+ * Resolve a task short reference ('#N') to a branch name.
+ *
+ * Current implementation: treats the digits as a 1-based index into the
+ * supplied running-sandbox list (ls view order). This is the *only*
+ * resolution path until the global task-short-id registry lands in a
+ * follow-up task; do NOT read task.md or scan .agents/workspace/ from this
+ * helper here.
+ *
+ * Precondition: callers MUST gate on isTaskShortRef(arg) === true before
+ * constructing ctx and calling this function. Throws when arg is a valid
+ * short ref but cannot be resolved (out of range, no running sandboxes,
+ * etc.); the caller surfaces the error to the user.
+ */
+export function resolveTaskShortRef(arg, ctx) {
+    const n = Number(arg.slice(1));
+    if (n < 1) {
+        throw new Error(`Invalid sandbox index '${arg}': must be >= 1`);
+    }
+    const { running } = ctx;
+    if (running.length === 0) {
+        throw new Error(`No running sandbox to reference with '${arg}'`);
+    }
+    if (n > running.length) {
+        throw new Error(`No running sandbox at index '${arg}' (only ${running.length} running)`);
+    }
+    const row = running[n - 1];
+    if (!row.branch) {
+        throw new Error(`Cannot resolve branch for sandbox '${arg}' (container '${row.name}' missing branch label)`);
+    }
+    return row.branch;
+}
+//# sourceMappingURL=list-running.js.map

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

@@ -5,39 +5,24 @@ import pc from 'picocolors';
 import { loadConfig } from "../config.js";
 import { sandboxBranchLabel, sandboxLabel } from "../constants.js";
 import { detectEngine } from "../engine.js";
-import { runSafeEngine } from "../shell.js";
 import { resolveTools, toolProjectDirCandidates } from "../tools.js";
-const USAGE = 'Usage: ai sandbox ls';
-const CONTAINER_TABLE_HEADERS = ['NAMES', 'STATUS', 'BRANCH'];
-// Exported to lock the docker/podman-compatible format in unit tests.
-export function containerListFormat() {
-    return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
-}
-export function parseLabels(csv) {
-    if (!csv) {
-        return {};
-    }
-    const labels = {};
-    for (const pair of csv.split(',')) {
-        if (!pair) {
-            continue;
-        }
-        const eq = pair.indexOf('=');
-        if (eq < 0) {
-            continue;
-        }
-        labels[pair.slice(0, eq)] = pair.slice(eq + 1);
-    }
-    return labels;
-}
+import { fetchSandboxRows } from "./list-running.js";
+export { containerListFormat, parseLabels } from "./list-running.js";
+const USAGE = `Usage: ai sandbox ls
+
+Lists all containers for the current project. The leftmost '#' column
+numbers running sandboxes; use it as "ai sandbox exec '#N'" to enter one.
+Quote '#N' to avoid shell '#' comment handling.`;
+const CONTAINER_TABLE_HEADERS = ['#', 'NAMES', 'STATUS', 'BRANCH'];
 export function formatContainerTable(rows) {
-    const columns = rows.map((row) => [row.name, row.status, row.branch]);
+    const columns = rows.map((row) => [row.index, row.name, row.status, row.branch]);
     const widths = [
-        Math.max(CONTAINER_TABLE_HEADERS[0].length, ...rows.map((row) => row.name.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.status.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.branch.length))
+        Math.max(CONTAINER_TABLE_HEADERS[0].length, ...rows.map((row) => row.index.length)),
+        Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.name.length)),
+        Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.status.length)),
+        Math.max(CONTAINER_TABLE_HEADERS[3].length, ...rows.map((row) => row.branch.length))
     ];
-    const renderRow = (values) => `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2]}`.trimEnd();
+    const renderRow = (values) => `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2].padEnd(widths[2])}  ${values[3]}`.trimEnd();
     return [
         renderRow(CONTAINER_TABLE_HEADERS),
         ...columns.map((column) => renderRow(column))
@@ -58,27 +43,21 @@ export function ls(args = []) {
     const engine = detectEngine(config);
     const tools = resolveTools(config);
     const label = sandboxLabel(config);
-    const containers = runSafeEngine(engine, 'docker', [
-        'ps',
-        '-a',
-        '--filter',
-        `label=${label}`,
-        '--format',
-        containerListFormat()
-    ]);
+    const { running, nonRunning } = fetchSandboxRows(engine, label, sandboxBranchLabel(config));
     p.intro(pc.cyan(`Sandbox status for ${config.project}`));
     p.log.step('Containers');
-    if (!containers) {
+    const ordered = [...running, ...nonRunning];
+    if (ordered.length === 0) {
         p.log.warn('  No sandbox containers');
     }
     else {
-        const branchKey = sandboxBranchLabel(config);
-        const rows = containers.split('\n').map((line) => {
-            const [name = '', status = '', labelsCsv = ''] = line.split('\t');
-            const branch = parseLabels(labelsCsv)[branchKey] ?? '';
-            return { name, status, branch };
-        });
-        for (const line of formatContainerTable(rows)) {
+        const tableRows = ordered.map((row) => ({
+            index: row.index === null ? '' : String(row.index),
+            name: row.name,
+            status: row.status,
+            branch: row.branch
+        }));
+        for (const line of formatContainerTable(tableRows)) {
             process.stdout.write(`  ${line}\n`);
         }
     }

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

@@ -7,20 +7,20 @@ import { prepareDockerfile } from "../dockerfile.js";
 import { sandboxImageConfigLabel, sandboxLabel } from "../constants.js";
 import { detectEngine, ensureDocker } from "../engine.js";
 import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from "../shell.js";
-import { resolveTools, toolNpmPackagesArg } from "../tools.js";
+import { imageSignatureFields, resolveTools, toolNpmPackagesArg, toolShellInstallScriptBase64 } 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({
         dockerfile: preparedDockerfile.signature,
-        tools: tools.map((tool) => tool.npmPackage)
+        tools: imageSignatureFields(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,
@@ -38,6 +38,8 @@ export function buildArgs(config, tools, dockerfilePath, imageSignature, { engin
         `HOST_GID=${hostGid}`,
         '--build-arg',
         `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+        '--build-arg',
+        `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
         '--label',
         sandboxLabel(config),
         '--label',
@@ -46,6 +48,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 +64,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 +78,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 +89,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 +98,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/config.js

@@ -6,6 +6,7 @@ import pc from 'picocolors';
 import { validateSandboxEngine } from "./engine.js";
 import { hostJoin } from "./engines/wsl2-paths.js";
 import { findRuntimeEngineMismatches } from "./runtime-engines.js";
+import { parseCustomTools } from "./tools.js";
 const DEFAULTS = Object.freeze({
     engine: null,
     runtimes: ['node22'],
@@ -76,6 +77,7 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
                 '  Update "sandbox.runtimes" in .agents/.airc.json (e.g. "node22"), or relax "engines.node".\n'));
         }
     }
+    const customTools = parseCustomTools(sandbox.customTools, { home });
     return {
         repoRoot,
         configPath,
@@ -93,6 +95,7 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
         tools: Array.isArray(sandbox.tools) && sandbox.tools.length > 0
             ? [...sandbox.tools]
             : defaults.tools,
+        customTools,
         dockerfile,
         vm: {
             cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,