@fitlab-ai/agent-infra 0.6.5 → 0.7.0

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

@@ -7,7 +7,7 @@ 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] [--refresh]`;
@@ -15,7 +15,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);
@@ -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',

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,

package/dist/lib/sandbox/index.js

@@ -2,7 +2,8 @@ const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
-  exec <branch> [cmd...]       Enter sandbox or run a command
+  exec <branch | '#N'> [cmd...]
+                               Enter sandbox or run a command (use leftmost '#' column from 'ls')
   ls                           List sandboxes for the current project
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]

package/dist/lib/sandbox/runtimes/ai-tools.dockerfile

@@ -4,16 +4,20 @@ ENV OPENCODE_DISABLE_AUTOUPDATE=1
 ENV NPM_CONFIG_PREFIX=/home/devuser/.npm-global
 ENV PATH="/home/devuser/.npm-global/bin:${PATH}"
 
-ARG AI_TOOL_PACKAGES
-RUN if [ -z "${AI_TOOL_PACKAGES}" ]; then \
-      echo "AI_TOOL_PACKAGES build arg is required"; \
-      exit 1; \
-    fi && \
-    set -e && \
+ARG AI_TOOL_PACKAGES=
+RUN set -e && \
     for pkg in ${AI_TOOL_PACKAGES}; do \
       npm install -g "$pkg"; \
     done
 
+ARG AI_TOOLS_SHELL_INSTALL_B64=
+RUN if [ -n "${AI_TOOLS_SHELL_INSTALL_B64}" ]; then \
+      set -e && \
+      echo "${AI_TOOLS_SHELL_INSTALL_B64}" | base64 -d > /tmp/ai-tools-install.sh && \
+      bash /tmp/ai-tools-install.sh && \
+      rm /tmp/ai-tools-install.sh; \
+    fi
+
 RUN npm install -g pyright
 
 RUN mkdir -p /home/devuser/.local/share /home/devuser/.local/state

package/dist/lib/sandbox/tools.js

@@ -1,11 +1,12 @@
 import { safeNameCandidates, sanitizeBranchName } from "./constants.js";
 import { hostJoin } from "./engines/wsl2-paths.js";
+const TOOL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
 function createBuiltinTools(home, project) {
     return {
         'claude-code': {
             id: 'claude-code',
             name: 'Claude Code',
-            npmPackage: '@anthropic-ai/claude-code@stable',
+            install: { type: 'npm', cmd: '@anthropic-ai/claude-code@stable' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
             containerMount: '/home/devuser/.claude',
             versionCmd: 'claude --version',
@@ -35,7 +36,7 @@ function createBuiltinTools(home, project) {
         codex: {
             id: 'codex',
             name: 'Codex',
-            npmPackage: '@openai/codex',
+            install: { type: 'npm', cmd: '@openai/codex' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'codex'),
             containerMount: '/home/devuser/.codex',
             versionCmd: 'codex --version',
@@ -50,7 +51,7 @@ function createBuiltinTools(home, project) {
         opencode: {
             id: 'opencode',
             name: 'OpenCode',
-            npmPackage: 'opencode-ai',
+            install: { type: 'npm', cmd: 'opencode-ai' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'opencode'),
             containerMount: '/home/devuser/.local/share/opencode',
             versionCmd: 'opencode version',
@@ -69,7 +70,7 @@ function createBuiltinTools(home, project) {
         'gemini-cli': {
             id: 'gemini-cli',
             name: 'Gemini CLI',
-            npmPackage: '@google/gemini-cli',
+            install: { type: 'npm', cmd: '@google/gemini-cli' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'gemini-cli'),
             containerMount: '/home/devuser/.gemini',
             versionCmd: 'gemini --version',
@@ -84,15 +85,200 @@ function createBuiltinTools(home, project) {
         }
     };
 }
+export function builtinToolIds() {
+    return Object.keys(createBuiltinTools('', ''));
+}
 function validateTool(tool) {
-    if (!tool.npmPackage || !tool.containerMount.startsWith('/')) {
-        throw new Error(`Invalid sandbox tool descriptor: ${tool.id}`);
+    if (!tool.id || !TOOL_ID_PATTERN.test(tool.id)) {
+        throw new Error(`Invalid sandbox tool id: ${String(tool.id)}`);
+    }
+    if (!tool.install || (tool.install.type !== 'npm' && tool.install.type !== 'shell')) {
+        throw new Error(`Sandbox tool ${tool.id} has invalid install.type`);
+    }
+    if (!tool.install.cmd) {
+        throw new Error(`Sandbox tool ${tool.id} has empty install.cmd`);
+    }
+    if (!tool.containerMount || !tool.containerMount.startsWith('/')) {
+        throw new Error(`Sandbox tool ${tool.id} containerMount must be an absolute path`);
+    }
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function asString(value, field, context) {
+    if (typeof value !== 'string') {
+        throw new Error(`${context}: field "${field}" must be a string`);
+    }
+    return value;
+}
+function asOptionalNonEmptyString(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== 'string') {
+        throw new Error(`${context}: field "${field}" must be a string when provided`);
+    }
+    if (value.length === 0) {
+        throw new Error(`${context}: field "${field}" must be non-empty when provided`);
+    }
+    return value;
+}
+function asStringRecord(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isPlainObject(value)) {
+        throw new Error(`${context}: field "${field}" must be an object when provided`);
+    }
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+        if (typeof val !== 'string') {
+            throw new Error(`${context}: field "${field}.${key}" must be a string`);
+        }
+        out[key] = val;
+    }
+    return out;
+}
+function asStringArray(value, field, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "${field}" must be an array when provided`);
+    }
+    return value.map((item, index) => {
+        if (typeof item !== 'string') {
+            throw new Error(`${context}: field "${field}[${index}]" must be a string`);
+        }
+        return item;
+    });
+}
+function parseInstall(value, context) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${context}: field "install" must be an object`);
+    }
+    const type = value.type;
+    if (type !== 'npm' && type !== 'shell') {
+        throw new Error(`${context}: field "install.type" must be "npm" or "shell"`);
+    }
+    const cmd = asString(value.cmd, 'install.cmd', context);
+    if (!cmd) {
+        throw new Error(`${context}: field "install.cmd" must be non-empty`);
+    }
+    return { type, cmd };
+}
+function parseHostPreSeedFiles(value, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "hostPreSeedFiles" must be an array when provided`);
     }
+    return value.map((item, index) => {
+        if (!isPlainObject(item)) {
+            throw new Error(`${context}: field "hostPreSeedFiles[${index}]" must be an object`);
+        }
+        return {
+            hostPath: asString(item.hostPath, `hostPreSeedFiles[${index}].hostPath`, context),
+            sandboxName: asString(item.sandboxName, `hostPreSeedFiles[${index}].sandboxName`, context)
+        };
+    });
+}
+function parseHostPreSeedDirs(value, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "hostPreSeedDirs" must be an array when provided`);
+    }
+    return value.map((item, index) => {
+        if (!isPlainObject(item)) {
+            throw new Error(`${context}: field "hostPreSeedDirs[${index}]" must be an object`);
+        }
+        return {
+            hostDir: asString(item.hostDir, `hostPreSeedDirs[${index}].hostDir`, context),
+            sandboxSubdir: asString(item.sandboxSubdir, `hostPreSeedDirs[${index}].sandboxSubdir`, context)
+        };
+    });
+}
+function parseHostLiveMounts(value, context) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!Array.isArray(value)) {
+        throw new Error(`${context}: field "hostLiveMounts" must be an array when provided`);
+    }
+    return value.map((item, index) => {
+        if (!isPlainObject(item)) {
+            throw new Error(`${context}: field "hostLiveMounts[${index}]" must be an object`);
+        }
+        return {
+            hostPath: asString(item.hostPath, `hostLiveMounts[${index}].hostPath`, context),
+            containerSubpath: asString(item.containerSubpath, `hostLiveMounts[${index}].containerSubpath`, context)
+        };
+    });
+}
+export function parseCustomTool(entry, index, options) {
+    const context = `customTools[${index}]`;
+    if (!isPlainObject(entry)) {
+        throw new Error(`${context} must be an object`);
+    }
+    const id = asString(entry.id, 'id', context);
+    if (!TOOL_ID_PATTERN.test(id)) {
+        throw new Error(`${context}: field "id" must match ${TOOL_ID_PATTERN.source}`);
+    }
+    const containerMount = asOptionalNonEmptyString(entry.containerMount, 'containerMount', context)
+        ?? `/home/devuser/.${id}`;
+    if (!containerMount.startsWith('/')) {
+        throw new Error(`${context}: field "containerMount" must be an absolute path`);
+    }
+    const tool = {
+        id,
+        name: asOptionalNonEmptyString(entry.name, 'name', context) ?? id,
+        install: parseInstall(entry.install, context),
+        sandboxBase: hostJoin(options.home, '.agent-infra', 'sandboxes', id),
+        containerMount,
+        versionCmd: asOptionalNonEmptyString(entry.versionCmd, 'versionCmd', context) ?? `which ${id}`,
+        setupHint: asOptionalNonEmptyString(entry.setupHint, 'setupHint', context)
+            ?? `Run \`${id}\` inside the container to set up.`,
+        envVars: asStringRecord(entry.envVars, 'envVars', context),
+        hostPreSeedFiles: parseHostPreSeedFiles(entry.hostPreSeedFiles, context),
+        hostPreSeedDirs: parseHostPreSeedDirs(entry.hostPreSeedDirs, context),
+        pathRewriteFiles: asStringArray(entry.pathRewriteFiles, 'pathRewriteFiles', context),
+        hostLiveMounts: parseHostLiveMounts(entry.hostLiveMounts, context),
+        postSetupCmds: asStringArray(entry.postSetupCmds, 'postSetupCmds', context)
+    };
+    validateTool(tool);
+    return tool;
+}
+export function parseCustomTools(value, options) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (!Array.isArray(value)) {
+        throw new Error('sandbox: "customTools" must be an array');
+    }
+    return value.map((entry, index) => parseCustomTool(entry, index, options));
 }
 export function resolveTools(config) {
     const builtins = createBuiltinTools(config.home, config.project);
+    const customs = config.customTools ?? [];
+    const seen = new Set();
+    for (const tool of customs) {
+        if (builtins[tool.id]) {
+            throw new Error(`Custom sandbox tool id "${tool.id}" collides with a built-in tool`);
+        }
+        if (seen.has(tool.id)) {
+            throw new Error(`Duplicate sandbox tool id "${tool.id}" in customTools`);
+        }
+        seen.add(tool.id);
+    }
+    const merged = { ...builtins };
+    for (const tool of customs) {
+        merged[tool.id] = tool;
+    }
     return config.tools.map((id) => {
-        const tool = builtins[id];
+        const tool = merged[id];
         if (!tool) {
             throw new Error(`Unknown sandbox tool: ${id}`);
         }
@@ -110,6 +296,25 @@ export function toolProjectDirCandidates(tool, project) {
     return [hostJoin(tool.sandboxBase, project)];
 }
 export function toolNpmPackagesArg(tools) {
-    return tools.map((tool) => tool.npmPackage).join(' ');
+    return tools
+        .filter((tool) => tool.install.type === 'npm')
+        .map((tool) => tool.install.cmd)
+        .join(' ');
+}
+export function toolShellInstallScript(tools) {
+    const blocks = tools
+        .filter((tool) => tool.install.type === 'shell')
+        .map((tool) => `# install: ${tool.id}\n${tool.install.cmd}`);
+    if (blocks.length === 0) {
+        return '';
+    }
+    return ['#!/bin/bash', 'set -e', '', ...blocks, ''].join('\n');
+}
+export function toolShellInstallScriptBase64(tools) {
+    const script = toolShellInstallScript(tools);
+    return script ? Buffer.from(script, 'utf8').toString('base64') : '';
+}
+export function imageSignatureFields(tools) {
+    return tools.map((tool) => ({ id: tool.id, install: tool.install }));
 }
 //# sourceMappingURL=tools.js.map

package/dist/lib/update.js

@@ -121,6 +121,7 @@ async function cmdUpdate() {
     const platformAdded = !config.platform;
     const sandboxAdded = !config.sandbox;
     const labelsAdded = !config.labels;
+    const requiresPullRequestAdded = config.requiresPullRequest === undefined;
     let configChanged = changed;
     if (platformAdded) {
         config.platform = structuredClone(defaults.platform);
@@ -134,6 +135,10 @@ async function cmdUpdate() {
         config.labels = structuredClone(defaults.labels);
         configChanged = true;
     }
+    if (requiresPullRequestAdded) {
+        config.requiresPullRequest = defaults.requiresPullRequest;
+        configChanged = true;
+    }
     if (configChanged) {
         console.log('');
         if (hasNewEntries) {
@@ -145,7 +150,7 @@ async function cmdUpdate() {
                 ok(`  merged: ${entry}`);
             }
         }
-        else if (platformAdded || sandboxAdded || labelsAdded) {
+        else if (platformAdded || sandboxAdded || labelsAdded || requiresPullRequestAdded) {
             if (platformAdded) {
                 info(`Default platform config added to ${CONFIG_PATH}.`);
             }
@@ -155,6 +160,9 @@ async function cmdUpdate() {
             if (labelsAdded) {
                 info(`Default labels.in config added to ${CONFIG_PATH}.`);
             }
+            if (requiresPullRequestAdded) {
+                info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+            }
         }
         else {
             info(`File registry changed in ${CONFIG_PATH}.`);
@@ -168,6 +176,9 @@ async function cmdUpdate() {
         if (hasNewEntries && platformAdded) {
             info(`Default platform config added to ${CONFIG_PATH}.`);
         }
+        if (hasNewEntries && requiresPullRequestAdded) {
+            info(`Default requiresPullRequest=${defaults.requiresPullRequest} added to ${CONFIG_PATH}.`);
+        }
         fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
         ok(`Updated ${CONFIG_PATH}`);
     }

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/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 });
+  } 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,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;
+}