@fitlab-ai/agent-infra 0.6.4 → 0.7.0

package/lib/cp.ts

@@ -0,0 +1,177 @@
+import { spawnSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import { platform as currentPlatform, tmpdir as defaultTmpdir } from 'node:os';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { createClipboardAdapter, type ClipboardAdapter } from './sandbox/clipboard/index.ts';
+
+const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS NSPasteboard over ssh/scp.\n';
+const COMMAND_TIMEOUT_MS = 30_000;
+
+export type SpawnResult = {
+  status: number | null;
+  stdout: string;
+  stderr: string;
+  error?: Error;
+};
+
+type SpawnFn = (cmd: string, args: string[], input?: string) => SpawnResult;
+type CreateAdapterFn = (options?: { platformName?: NodeJS.Platform }) => ClipboardAdapter | null;
+type MkDTempFn = (prefix: string) => string;
+type WriteFileFn = (file: string, data: Buffer) => void;
+type RmFn = (target: string, options: { recursive: boolean; force: boolean }) => void;
+
+export type CpDeps = {
+  platform?: NodeJS.Platform;
+  createAdapter?: CreateAdapterFn;
+  spawnFn?: SpawnFn;
+  randomId?: () => string;
+  mkdtempFn?: MkDTempFn;
+  writeFileFn?: WriteFileFn;
+  rmFn?: RmFn;
+  tmpdir?: () => string;
+  writeStdout?: (chunk: string) => unknown;
+  writeStderr?: (chunk: string) => unknown;
+};
+
+export function runCommand(cmd: string, args: string[], input?: string): SpawnResult {
+  const result = spawnSync(cmd, args, {
+    input,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+    timeout: COMMAND_TIMEOUT_MS
+  });
+
+  return {
+    status: result.status,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+    error: result.error
+  };
+}
+
+export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number> {
+  const {
+    platform = currentPlatform(),
+    createAdapter = createClipboardAdapter,
+    spawnFn = runCommand,
+    randomId = randomUUID,
+    mkdtempFn = fs.mkdtempSync,
+    writeFileFn = fs.writeFileSync,
+    rmFn = fs.rmSync,
+    tmpdir = defaultTmpdir,
+    writeStdout = (chunk: string) => process.stdout.write(chunk),
+    writeStderr = (chunk: string) => process.stderr.write(chunk)
+  } = deps;
+
+  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
+    writeStdout(USAGE);
+    return 0;
+  }
+
+  let positionals: string[];
+  try {
+    ({ positionals } = parseArgs({ args, allowPositionals: true, strict: true }));
+  } catch {
+    writeStderr(USAGE);
+    return 1;
+  }
+
+  const alias = positionals[0];
+  if (!alias || positionals.length !== 1) {
+    writeStderr(USAGE);
+    return 1;
+  }
+  if (alias.startsWith('-')) {
+    writeStderr(`invalid ssh alias '${alias}': must not start with '-'\n`);
+    return 1;
+  }
+
+  if (platform !== 'darwin') {
+    writeStderr(`ai cp currently supports macOS senders only (got ${platform})\n`);
+    return 1;
+  }
+
+  const adapter = createAdapter({ platformName: platform });
+  const png = adapter?.readImagePng() ?? null;
+  if (png === null) {
+    writeStderr('no image on clipboard\n');
+    return 1;
+  }
+
+  let uploaded = false;
+  let localTmpDir: string | null = null;
+  let remotePath: string | null = null;
+
+  try {
+    localTmpDir = mkdtempFn(path.join(tmpdir(), 'agent-infra-cp-'));
+    const localPng = path.join(localTmpDir, 'clipboard.png');
+    writeFileFn(localPng, png);
+
+    remotePath = `/tmp/agent-infra-cp-${randomId()}.png`;
+    const upload = spawnFn('scp', [
+      '-o',
+      'BatchMode=yes',
+      '-o',
+      'ConnectTimeout=10',
+      localPng,
+      `${alias}:${remotePath}`
+    ]);
+    if (upload.status !== 0) {
+      writeStderr(`failed to upload image to ${alias}:\n${commandDetail(upload)}\n`);
+      return 1;
+    }
+    uploaded = true;
+
+    // Remote write currently targets macOS only: it pipes an AppleScript to the
+    // remote `osascript` to set its NSPasteboard. This is the extension point for
+    // other remote platforms later (e.g. dispatch on remote OS to wl-copy/xclip
+    // on Linux); a non-macOS remote fails here with a clear non-zero error today.
+    const setRemote = spawnFn('ssh', [
+      '-o',
+      'BatchMode=yes',
+      '-o',
+      'ConnectTimeout=10',
+      alias,
+      'osascript',
+      '-'
+    ], remoteSetScript(remotePath));
+    if (setRemote.status !== 0) {
+      writeStderr(`failed to set remote clipboard on ${alias}:\n${commandDetail(setRemote)}\n`);
+      return 1;
+    }
+
+    writeStdout(`copied clipboard image to ${alias}\n`);
+    return 0;
+  } finally {
+    if (uploaded && remotePath) {
+      spawnFn('ssh', [
+        '-o',
+        'BatchMode=yes',
+        '-o',
+        'ConnectTimeout=10',
+        alias,
+        'rm',
+        '-f',
+        remotePath
+      ]);
+    }
+    if (localTmpDir) {
+      rmFn(localTmpDir, { recursive: true, force: true });
+    }
+  }
+}
+
+function commandDetail(result: SpawnResult): string {
+  const detail = result.stderr || result.error?.message || result.stdout || 'unknown error';
+  return detail.trimEnd();
+}
+
+function remoteSetScript(remotePath: string): string {
+  const escapedPath = remotePath.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+  return [
+    `set theFile to POSIX file "${escapedPath}"`,
+    'set the clipboard to (read theFile as «class PNGf»)'
+  ].join('\n');
+}

package/lib/defaults.json

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

package/lib/init.ts

@@ -24,6 +24,7 @@ type Defaults = {
   files: FileRegistry;
   sandbox: Record<string, unknown>;
   labels: Record<string, unknown>;
+  requiresPullRequest: boolean;
 };
 
 type AgentConfig = {
@@ -31,6 +32,7 @@ type AgentConfig = {
   org: string;
   language: string;
   platform: { type: string };
+  requiresPullRequest: boolean;
   templateVersion: string;
   sandbox: Record<string, unknown>;
   labels: Record<string, unknown>;
@@ -207,6 +209,13 @@ async function cmdInit(): Promise<void> {
     );
   }
 
+  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)',
     ''
@@ -280,6 +289,7 @@ async function cmdInit(): Promise<void> {
     org: orgName,
     language,
     platform: { type: platformType },
+    requiresPullRequest,
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
     labels: structuredClone(defaults.labels),

package/lib/sandbox/clipboard/bridge.ts

@@ -1,4 +1,5 @@
 import { StringDecoder } from 'node:string_decoder';
+import { spawnSync } from 'node:child_process';
 import { createClipboardAdapter, type ClipboardAdapter } from './index.ts';
 import { buildBracketedPaste, CtrlVDetector, type CtrlVMatch } from './keys.ts';
 import {
@@ -32,6 +33,26 @@ type BridgeOptions = {
 const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
 const PARTIAL_ESCAPE_FLUSH_MS = 30;
 
+// Node's stdin.setRawMode(true) uses libuv's RAW mode, which (unlike the
+// cfmakeraw that `docker exec -it` applies on the non-bridge path) keeps ONLCR
+// set on the shared host TTY. With ONLCR on, the kernel rewrites the bare \n
+// that tmux emits after homing the cursor inside the right pane into \r\n,
+// snapping the cursor to column 1 so the following erase/redraw wipes the left
+// pane. Clearing OPOST brings the host TTY in line with the non-bridge path.
+// Best-effort: setRawMode(false) on teardown restores the original termios, and
+// a missing/failed stty only reinstates the redraw glitch.
+function disableOutputPostProcessing(stdin: NodeJS.ReadStream): void {
+  const candidate = (stdin as { fd?: unknown }).fd;
+  if (typeof candidate !== 'number') {
+    return;
+  }
+  try {
+    spawnSync('stty', ['-opost'], { stdio: [candidate, 'ignore', 'ignore'] });
+  } catch {
+    // stty unavailable or fd is not a tty; leave the terminal as-is.
+  }
+}
+
 export async function runInteractiveWithClipboardBridge(options: BridgeOptions): Promise<number> {
   const {
     engine,
@@ -56,14 +77,11 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
     return runInteractive(engine, 'docker', dockerArgs);
   }
 
-  if (platformName !== 'darwin') {
-    return runInteractive(engine, 'docker', dockerArgs);
-  }
   if (!stdin.isTTY || !stdout.isTTY) {
     return fallback('host stdin/stdout is not a TTY');
   }
   if (!adapter) {
-    return fallback('macOS clipboard adapter is unavailable');
+    return fallback('no clipboard adapter available on this platform');
   }
   const available = adapter.available();
   if (!available.ok) {
@@ -185,6 +203,7 @@ async function runBridge({
 
   try {
     stdin.setRawMode?.(true);
+    disableOutputPostProcessing(stdin);
     stdin.resume();
     stdin.on('data', onData);
     stdout.on('resize', onResize);

package/lib/sandbox/clipboard/index.ts

@@ -6,8 +6,17 @@ export type ClipboardAdapter = DarwinClipboardAdapter;
 export function createClipboardAdapter({
   platformName = platform()
 }: { platformName?: NodeJS.Platform } = {}): ClipboardAdapter | null {
-  if (platformName !== 'darwin') {
-    return null;
+  switch (platformName) {
+    case 'darwin':
+      return createDarwinClipboardAdapter();
+    case 'linux':
+      // Future work: dispatch based on $WAYLAND_DISPLAY (wl-paste) or $DISPLAY (xclip);
+      // see Issue #386 follow-up. Returning null disables the bridge for now.
+      return null;
+    case 'win32':
+      // Future work: native Win32 clipboard reader. Returning null disables the bridge.
+      return null;
+    default:
+      return null;
   }
-  return createDarwinClipboardAdapter();
 }

package/lib/sandbox/commands/create.ts

@@ -36,13 +36,20 @@ import {
   runVerboseEngine
 } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
-import { resolveTools, toolConfigDirCandidates, toolNpmPackagesArg } from '../tools.ts';
+import {
+  imageSignatureFields,
+  resolveTools,
+  toolConfigDirCandidates,
+  toolNpmPackagesArg,
+  toolShellInstallScriptBase64
+} from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { resolveBuildUid } from '../engines/native.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
+import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.ts';
 import {
   prepareClaudeCredentials,
   redactCommandError,
@@ -112,7 +119,7 @@ function buildSignature(preparedDockerfile: PreparedDockerfile, tools: SandboxTo
   return createHash('sha256')
     .update(JSON.stringify({
       dockerfile: preparedDockerfile.signature,
-      tools: tools.map((tool) => tool.npmPackage)
+      tools: imageSignatureFields(tools)
     }))
     .digest('hex')
     .slice(0, 12);
@@ -1062,6 +1069,8 @@ export function buildImage(
     `HOST_GID=${hostGid}`,
     '--build-arg',
     `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+    '--build-arg',
+    `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
     '--label',
     sandboxLabel(config),
     '--label',
@@ -1287,6 +1296,13 @@ export async function create(args: string[]): Promise<void> {
             message(`Created default sandbox aliases at ${aliasesFile.path}`);
           }
 
+          const readmeResults = ensureSandboxDiscoveryReadmes(effectiveConfig, branch);
+          for (const { created, path: readmePath } of readmeResults) {
+            if (created) {
+              message(`Created discovery README at ${readmePath}`);
+            }
+          }
+
           const gitconfigPath = path.join(effectiveConfig.home, '.gitconfig');
           const gitconfigContent = fs.existsSync(gitconfigPath)
             ? fs.readFileSync(gitconfigPath, 'utf8')

package/lib/sandbox/commands/enter.ts

@@ -1,5 +1,5 @@
 import { loadConfig } from '../config.ts';
-import { assertValidBranchName, containerNameCandidates } from '../constants.ts';
+import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import {
   formatCredentialWarnings,
@@ -13,8 +13,12 @@ import { resolveTaskBranch } from '../task-resolver.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.ts';
 import { detectHostTimezone } from '../host-timezone.ts';
+import { fetchSandboxRows, isTaskShortRef, resolveTaskShortRef } from './list-running.ts';
 
-const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
+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)
@@ -45,6 +49,37 @@ export function hostTimezoneEnvFlags(detect = detectHostTimezone): string[] {
   return tz ? ['-e', `TZ=${tz}`] : [];
 }
 
+export function clipboardBridgeDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  const value = (env.AI_SANDBOX_NO_CLIPBOARD_BRIDGE ?? '').trim().toLowerCase();
+  return value === '1' || value === 'true' || value === 'yes';
+}
+
+export function runSandboxInteractive(params: {
+  engine: string;
+  dockerArgs: string[];
+  container: string;
+  home: string;
+  env?: NodeJS.ProcessEnv;
+  runBridge?: typeof runInteractiveWithClipboardBridge;
+  runInteractive?: typeof runInteractiveEngine;
+}): number | Promise<number> {
+  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: ReturnType<typeof reconcileClaudeCredentials>,
   isTTY = process.stderr.isTTY
@@ -84,8 +119,14 @@ export async function enter(args: string[]): Promise<number> {
   const config = loadConfig();
   validateClaudeCredentialsEnvOverride();
   const engine = detectEngine(config);
-  const [branchOrTaskId = '', ...cmd] = args;
-  const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
+  const [firstArg = '', ...cmd] = args;
+  let branch: string;
+  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));
@@ -115,9 +156,10 @@ export async function enter(args: string[]): Promise<number> {
       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/lib/sandbox/commands/list-running.ts

@@ -0,0 +1,135 @@
+import { runSafeEngine } from '../shell.ts';
+
+export type SandboxRow = {
+  name: string;
+  status: string;
+  branch: string;
+  running: boolean;
+  index: number | null;
+};
+
+export function containerListFormat(): string {
+  return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
+}
+
+export function parseLabels(csv: string): Record<string, string> {
+  if (!csv) {
+    return {};
+  }
+
+  const labels: Record<string, string> = {};
+  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: string, branchKey: string): SandboxRow[] {
+  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: SandboxRow[]): {
+  running: SandboxRow[];
+  nonRunning: SandboxRow[];
+} {
+  const byName = (a: SandboxRow, b: SandboxRow): number => {
+    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: string,
+  label: string,
+  branchKey: string
+): { running: SandboxRow[]; nonRunning: SandboxRow[] } {
+  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: string): boolean {
+  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: string,
+  ctx: { running: SandboxRow[] }
+): string {
+  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;
+}

package/lib/sandbox/commands/ls.ts

@@ -5,51 +5,36 @@ import pc from 'picocolors';
 import { loadConfig } from '../config.ts';
 import { sandboxBranchLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
-import { runSafeEngine } from '../shell.ts';
 import { resolveTools, toolProjectDirCandidates } from '../tools.ts';
+import { fetchSandboxRows } from './list-running.ts';
 
-const USAGE = 'Usage: ai sandbox ls';
-const CONTAINER_TABLE_HEADERS = ['NAMES', 'STATUS', 'BRANCH'] as const;
+export { containerListFormat, parseLabels } from './list-running.ts';
+
+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'] as const;
 
 type ContainerTableRow = {
+  index: string;
   name: string;
   status: string;
   branch: string;
 };
 
-// Exported to lock the docker/podman-compatible format in unit tests.
-export function containerListFormat(): string {
-  return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
-}
-
-export function parseLabels(csv: string): Record<string, string> {
-  if (!csv) {
-    return {};
-  }
-
-  const labels: Record<string, string> = {};
-  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 formatContainerTable(rows: ContainerTableRow[]): string[] {
-  const columns = rows.map((row) => [row.name, row.status, row.branch] as const);
+  const columns = rows.map((row) => [row.index, row.name, row.status, row.branch] as const);
   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))
   ] as const;
-  const renderRow = (values: readonly [string, string, string]): string =>
-    `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2]}`.trimEnd();
+  const renderRow = (values: readonly [string, string, string, string]): string =>
+    `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2].padEnd(widths[2])}  ${values[3]}`.trimEnd();
 
   return [
     renderRow(CONTAINER_TABLE_HEADERS),
@@ -75,28 +60,22 @@ export function ls(args: string[] = []): void {
   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: ContainerTableRow[] = 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`);
     }
   }