@fitlab-ai/agent-infra 0.6.5 → 0.7.1

package/lib/init.ts

@@ -3,11 +3,18 @@ import path from 'node:path';
 import { execSync } from 'node:child_process';
 import { platform } from 'node:os';
 import { info, ok, err } from './log.ts';
-import { prompt, select, closePrompt } from './prompt.ts';
+import { prompt, select, multiSelect, closePrompt } from './prompt.ts';
 import { resolveTemplateDir } from './paths.ts';
 import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.ts';
 import { enginesForPlatform } from './sandbox/engines/index.ts';
 import { VERSION } from './version.ts';
+import {
+  BUILTIN_TUI_IDS,
+  BUILTIN_TUI_DISPLAY,
+  isPathOwnedByDisabledTUI,
+  resolveEnabledTUIs
+} from './builtin-tuis.ts';
+import type { BuiltinTUIId } from './builtin-tuis.ts';
 
 type FileRegistry = {
   managed: string[];
@@ -23,7 +30,9 @@ type SourceEntry = {
 type Defaults = {
   files: FileRegistry;
   sandbox: Record<string, unknown>;
+  task: { shortIdLength: number };
   labels: Record<string, unknown>;
+  requiresPullRequest: boolean;
 };
 
 type AgentConfig = {
@@ -31,10 +40,13 @@ type AgentConfig = {
   org: string;
   language: string;
   platform: { type: string };
+  requiresPullRequest: boolean;
   templateVersion: string;
   sandbox: Record<string, unknown>;
+  task: { shortIdLength: number };
   labels: Record<string, unknown>;
   files: FileRegistry;
+  tuis: string[];
   templates?: { sources: SourceEntry[] };
   skills?: { sources: SourceEntry[] };
 };
@@ -58,10 +70,15 @@ function isPathOwnedByOtherPlatform(relativePath: string, platformType: string):
   return candidate !== platformType;
 }
 
-function buildDefaultFiles(platformType: string): FileRegistry {
+function buildDefaultFiles(platformType: string, enabledTUIs: Set<BuiltinTUIId>): FileRegistry {
+  const ownedByDisabled = (entry: string) => isPathOwnedByDisabledTUI(entry, enabledTUIs);
   return {
-    managed: (defaults.files.managed || []).filter((entry) => !isPathOwnedByOtherPlatform(entry, platformType)),
-    merged: (defaults.files.merged || []).filter((entry) => !isPathOwnedByOtherPlatform(entry, platformType)),
+    managed: (defaults.files.managed || []).filter(
+      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
+    ),
+    merged: (defaults.files.merged || []).filter(
+      (entry) => !isPathOwnedByOtherPlatform(entry, platformType) && !ownedByDisabled(entry)
+    ),
     ejected: structuredClone(defaults.files.ejected || [])
   };
 }
@@ -207,6 +224,27 @@ async function cmdInit(): Promise<void> {
     );
   }
 
+  const requiresPRChoice = await select(
+    'Require Pull Request flow?',
+    ['yes', 'no'],
+    'yes'
+  );
+  const requiresPullRequest = requiresPRChoice !== 'no';
+
+  let enabledTUIs: string[];
+  try {
+    enabledTUIs = await multiSelect(
+      'Built-in TUI command files to install/manage',
+      BUILTIN_TUI_IDS.map((id) => ({ id, label: BUILTIN_TUI_DISPLAY[id] }))
+    );
+  } catch (e) {
+    err(e instanceof Error ? e.message : String(e));
+    closePrompt();
+    process.exitCode = 1;
+    return;
+  }
+  const enabledTUISet = resolveEnabledTUIs(enabledTUIs);
+
   const templateSources = parseLocalSources(await prompt(
     'Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)',
     ''
@@ -250,29 +288,35 @@ async function cmdInit(): Promise<void> {
   );
   ok('Installed .agents/skills/update-agent-infra/');
 
-  // install Claude command
-  renderFile(
-    path.join(templateDir, '.claude', 'commands', claudeSrc),
-    path.join('.claude', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Installed .claude/commands/update-agent-infra.md');
+  // 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
+    );
+    ok('Installed .claude/commands/update-agent-infra.md');
+  }
 
-  // install Gemini command
-  renderFile(
-    path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
-    path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
-    replacements
-  );
-  ok(`Installed .gemini/commands/${project}/update-agent-infra.toml`);
+  // install Gemini command (only if enabled)
+  if (enabledTUISet.has('gemini-cli')) {
+    renderFile(
+      path.join(templateDir, '.gemini', 'commands', '_project_', geminiSrc),
+      path.join('.gemini', 'commands', project, 'update-agent-infra.toml'),
+      replacements
+    );
+    ok(`Installed .gemini/commands/${project}/update-agent-infra.toml`);
+  }
 
-  // install OpenCode command
-  renderFile(
-    path.join(templateDir, '.opencode', 'commands', opencodeSrc),
-    path.join('.opencode', 'commands', 'update-agent-infra.md'),
-    replacements
-  );
-  ok('Installed .opencode/commands/update-agent-infra.md');
+  // install OpenCode command (only if enabled)
+  if (enabledTUISet.has('opencode')) {
+    renderFile(
+      path.join(templateDir, '.opencode', 'commands', opencodeSrc),
+      path.join('.opencode', 'commands', 'update-agent-infra.md'),
+      replacements
+    );
+    ok('Installed .opencode/commands/update-agent-infra.md');
+  }
 
   // generate .agents/.airc.json
   const config: AgentConfig = {
@@ -280,10 +324,13 @@ async function cmdInit(): Promise<void> {
     org: orgName,
     language,
     platform: { type: platformType },
+    requiresPullRequest,
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
+    task: structuredClone(defaults.task),
     labels: structuredClone(defaults.labels),
-    files: buildDefaultFiles(platformType)
+    files: buildDefaultFiles(platformType, enabledTUISet),
+    tuis: enabledTUIs
   };
 
   if (sandboxEngine) {
@@ -310,15 +357,30 @@ async function cmdInit(): Promise<void> {
   console.log('');
   ok('Project initialized successfully!');
   console.log('');
-  console.log('  Next step: open this project in any AI TUI and run:');
-  console.log('');
-  console.log('    Claude Code / OpenCode:  /update-agent-infra');
-  console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
-  console.log('    Codex CLI:               $update-agent-infra');
-  console.log('');
-  console.log('  This will render all templates and set up the full');
-  console.log('  AI collaboration infrastructure.');
-  console.log('');
+  if (enabledTUISet.size === 0) {
+    console.log('  No built-in TUI selected.');
+    console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
+    console.log('');
+  } else {
+    console.log('  Next step: open this project in any AI TUI and run:');
+    console.log('');
+    const claudeOrOpencode: string[] = [];
+    if (enabledTUISet.has('claude-code')) claudeOrOpencode.push('Claude Code');
+    if (enabledTUISet.has('opencode')) claudeOrOpencode.push('OpenCode');
+    if (claudeOrOpencode.length > 0) {
+      console.log(`    ${claudeOrOpencode.join(' / ')}:  /update-agent-infra`);
+    }
+    if (enabledTUISet.has('gemini-cli')) {
+      console.log(`    Gemini CLI:              /${project}:update-agent-infra`);
+    }
+    if (enabledTUISet.has('codex')) {
+      console.log('    Codex CLI:               $update-agent-infra');
+    }
+    console.log('');
+    console.log('  This will render all templates and set up the full');
+    console.log('  AI collaboration infrastructure.');
+    console.log('');
+  }
 }
 
 export { cmdInit };

package/lib/prompt.ts

@@ -86,6 +86,59 @@ async function select(question: string, choices: string[], defaultValue?: string
   return trimmed;
 }
 
+async function multiSelect(
+  question: string,
+  choices: { id: string; label: string }[]
+): Promise<string[]> {
+  process.stdout.write(`  ${question}:\n`);
+  const idWidth = Math.max(...choices.map((c) => c.id.length));
+  choices.forEach((c, i) => {
+    process.stdout.write(`      ${i + 1}) ${c.id.padEnd(idWidth)}  (${c.label})\n`);
+  });
+  ask('Enter comma-separated numbers or ids to keep, or "none" to select nothing [default: all]: ');
+
+  setupInterface();
+
+  const line = await nextLine();
+  // Strictly distinguish bare Enter (null/empty string) from whitespace input.
+  if (line === null || line === '') return choices.map((c) => c.id);
+  // Explicit empty selection: "none" means deliberately zero built-in choices.
+  if (line.trim().toLowerCase() === 'none') return [];
+
+  const tokens = line.split(',').map((t) => t.trim());
+  if (tokens.some((t) => t === '')) {
+    throw new Error(`Invalid selection input: "${line}" (empty token)`);
+  }
+
+  const idSet = new Set(choices.map((c) => c.id));
+  const seenIds = new Set<string>();
+  for (const t of tokens) {
+    let resolvedId: string | undefined;
+    if (/^[0-9]+$/.test(t)) {
+      const n = Number.parseInt(t, 10);
+      if (n < 1 || n > choices.length) {
+        throw new Error(`Selection out of range: "${t}" (expected 1..${choices.length})`);
+      }
+      resolvedId = choices[n - 1]!.id;
+    } else if (idSet.has(t)) {
+      resolvedId = t;
+    } else {
+      throw new Error(`Unknown TUI selection token: "${t}"`);
+    }
+    if (seenIds.has(resolvedId)) {
+      throw new Error(`Duplicate selection: "${t}" resolves to already-selected "${resolvedId}"`);
+    }
+    seenIds.add(resolvedId);
+  }
+
+  // Normalize to prompt order: users can type tokens in any order, but the
+  // persisted array follows the canonical choices order to keep .airc.json
+  // diffs stable. An empty result here is impossible (tokens.length > 0 and
+  // every token resolves to an id), so no separate empty guard is needed —
+  // explicit "none" handled above.
+  return choices.map((c) => c.id).filter((id) => seenIds.has(id));
+}
+
 function closePrompt(): void {
   if (_rl) {
     _rl.close();
@@ -94,4 +147,4 @@ function closePrompt(): void {
   }
 }
 
-export { prompt, select, closePrompt };
+export { prompt, select, multiSelect, closePrompt };

package/lib/sandbox/commands/create.ts

@@ -36,7 +36,13 @@ 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';
@@ -113,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);
@@ -1063,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',

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)
@@ -115,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, repoRoot: config.repoRoot });
+  } 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));

package/lib/sandbox/commands/list-running.ts

@@ -0,0 +1,188 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+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);
+}
+
+type RegistryLookup =
+  | { status: 'miss' }
+  | { status: 'hit'; branch: string };
+
+/**
+ * Try to resolve a short ref against the global task-short-id registry.
+ *
+ * Tri-state semantics (review-code Round 1 M-1 fix):
+ *   - 'miss'     → script reports no entry (or registry script missing). Caller may fall back.
+ *   - 'hit'      → registry resolved to a task id and branch is found in task.md.
+ *   - throws     → registry hit but task.md is missing or branch metadata is unparseable;
+ *                   surfacing this error is critical — never silently fall back to running index.
+ */
+function tryResolveFromRegistry(arg: string, repoRoot: string): RegistryLookup {
+  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+  if (!fs.existsSync(scriptPath)) return { status: 'miss' };
+  const result = spawnSync('node', [scriptPath, 'resolve', arg], { encoding: 'utf8', cwd: repoRoot });
+  if (result.status !== 0) return { status: 'miss' };
+  const taskId = (result.stdout || '').trim();
+  if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) {
+    throw new Error(
+      `Registry returned malformed task id for '${arg}': ${JSON.stringify(taskId)}`
+    );
+  }
+  for (const sub of ['active', 'completed', 'blocked', 'archive']) {
+    const taskMdPath = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+    if (!fs.existsSync(taskMdPath)) continue;
+    const content = fs.readFileSync(taskMdPath, 'utf8');
+    const fm = content.match(/^branch:\s*(.+)$/m);
+    if (fm?.[1]?.trim()) {
+      return { status: 'hit', branch: fm[1].trim().replace(/^(["'])(.*)\1$/, '$2') };
+    }
+    const ctx = content.match(/^- \*\*(?:分支|Branch)\*\*：[ \t]*`?([^`\n]+)`?$/m);
+    if (ctx?.[1]?.trim()) {
+      return { status: 'hit', branch: ctx[1].trim().replace(/^(["'])(.*)\1$/, '$2') };
+    }
+    throw new Error(
+      `Short ref '${arg}' resolved to task ${taskId} but task.md has no branch field`
+    );
+  }
+  throw new Error(
+    `Short ref '${arg}' resolved to task ${taskId} but task.md was not found under any workspace dir`
+  );
+}
+
+function resolveByRunningIndex(arg: string, running: SandboxRow[]): string {
+  const n = Number(arg.slice(1));
+  if (n < 1) {
+    throw new Error(`Invalid sandbox index '${arg}': must be >= 1`);
+  }
+  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;
+}
+
+/**
+ * Resolve a task short reference ('#N') to a branch name for the sandbox entrypoint.
+ *
+ * Resolution order (sandbox fallback mode, plan-r7 C2):
+ *   1. Try the global task-short-id registry under repoRoot. If hit, look up the
+ *      branch from the matching task.md.
+ *   2. Fallback to the running-sandbox list index (preserves the #414 ls-index
+ *      behaviour; long-term contract per analysis-r5).
+ *
+ * Precondition: callers MUST gate on isTaskShortRef(arg) === true.
+ */
+export function resolveTaskShortRef(
+  arg: string,
+  ctx: { running: SandboxRow[]; repoRoot?: string }
+): string {
+  if (ctx.repoRoot) {
+    const lookup = tryResolveFromRegistry(arg, ctx.repoRoot);
+    if (lookup.status === 'hit') return lookup.branch;
+    // 'miss' falls through to ls-index fallback (preserves #414 behaviour); 'hit-but-invalid' already threw above.
+  }
+  return resolveByRunningIndex(arg, ctx.running);
+}

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`);
     }
   }