@fitlab-ai/agent-infra 0.7.1 → 0.7.3

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

@@ -0,0 +1,122 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { formatTable } from "../../table.js";
+import { parseTaskFrontmatter, extractTitle } from "../frontmatter.js";
+import { loadShortIdByTaskId } from "../short-id.js";
+const USAGE = `Usage: ai task ls [--all | --blocked | --completed]
+
+Lists tasks under .agents/workspace/. Defaults to active tasks only.
+  --all         Include active + blocked + completed (excludes archive)
+  --blocked     Only blocked tasks
+  --completed   Only completed tasks
+
+Columns: # (display-only row number) / SHORT (task short id, usable as an argument) / type / status / current_step / branch / title
+`;
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const TABLE_HEADERS = ['#', 'SHORT', 'TYPE', 'STATUS', 'STEP', 'BRANCH', 'TITLE'];
+function detectRepoRoot() {
+    try {
+        return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+    }
+    catch {
+        throw new Error('ai task: current directory is not inside a git repository');
+    }
+}
+function parseSelection(args) {
+    const positional = args.filter((a) => !a.startsWith('--'));
+    if (positional.length > 0) {
+        return {
+            ok: false,
+            message: `ai task ls: unexpected positional argument(s): ${positional.join(' ')}`
+        };
+    }
+    const flags = args.filter((a) => a.startsWith('--'));
+    if (flags.length === 0)
+        return { ok: true, selection: ['active'] };
+    if (flags.length > 1) {
+        return {
+            ok: false,
+            message: 'ai task ls: pass at most one of --all / --blocked / --completed'
+        };
+    }
+    switch (flags[0]) {
+        case '--all':
+            return { ok: true, selection: ['active', 'blocked', 'completed'] };
+        case '--blocked':
+            return { ok: true, selection: ['blocked'] };
+        case '--completed':
+            return { ok: true, selection: ['completed'] };
+        default:
+            return { ok: false, message: `ai task ls: unknown flag: ${flags[0]}` };
+    }
+}
+function collectTasks(repoRoot, state) {
+    const dir = path.join(repoRoot, '.agents', 'workspace', state);
+    if (!fs.existsSync(dir))
+        return [];
+    // Short ids live only in the registry and only for active tasks; archived
+    // (blocked/completed) tasks have released their short id and render '-'.
+    const shortIdByTaskId = state === 'active' ? loadShortIdByTaskId(repoRoot) : new Map();
+    const rows = [];
+    for (const entry of fs.readdirSync(dir).sort()) {
+        if (!TASK_ID_RE.test(entry))
+            continue;
+        const taskMdPath = path.join(dir, entry, 'task.md');
+        if (!fs.existsSync(taskMdPath))
+            continue;
+        const content = fs.readFileSync(taskMdPath, 'utf8');
+        const fm = parseTaskFrontmatter(content);
+        const title = extractTitle(content);
+        const shortId = shortIdByTaskId.get(entry) ?? '-';
+        rows.push({
+            shortId,
+            type: fm.type ?? '-',
+            status: fm.status ?? state,
+            step: fm.current_step ?? '-',
+            branch: fm.branch ?? '-',
+            title: title || fm.id || entry
+        });
+    }
+    return rows;
+}
+function ls(args = []) {
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const result = parseSelection(args);
+    if (!result.ok) {
+        process.stderr.write(`${result.message}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const { selection } = result;
+    const repoRoot = detectRepoRoot();
+    const rows = [];
+    for (const state of selection) {
+        rows.push(...collectTasks(repoRoot, state));
+    }
+    if (rows.length === 0) {
+        process.stdout.write(`No tasks under .agents/workspace/${selection.join('|')}\n`);
+        return;
+    }
+    const tableRows = rows.map((r, i) => [
+        String(i + 1),
+        r.shortId,
+        r.type,
+        r.status,
+        r.step,
+        r.branch,
+        r.title
+    ]);
+    for (const line of formatTable(TABLE_HEADERS, tableRows, { zebra: Boolean(process.stdout.isTTY) })) {
+        process.stdout.write(`${line}\n`);
+    }
+    process.stdout.write(`Total: ${rows.length} tasks\n`);
+}
+export { ls };
+//# sourceMappingURL=ls.js.map

package/dist/lib/task/commands/show.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { normalizeShortIdInput } from "../short-id.js";
+const USAGE = `Usage: ai task show <N | #N | TASK-id>
+
+Prints the task.md content for the matching task.
+  N (bare numeric)   Recommended; resolves the active short id via the registry.
+  '#N'               Compatibility form for old commands.
+  TASK-YYYYMMDD-HHMMSS  Locates a task in active / blocked / completed / archive.
+`;
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+// Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
+// Note: `archive` uses a three-level YYYY/MM/DD layout and is handled separately.
+const FLAT_WORKSPACE_DIRS = ['active', 'blocked', 'completed'];
+function detectRepoRoot() {
+    try {
+        return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+    }
+    catch {
+        throw new Error('ai task: current directory is not inside a git repository');
+    }
+}
+function readShortIdLength(repoRoot) {
+    try {
+        const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+        const v = cfg?.task?.shortIdLength;
+        if (typeof v === 'number' && Number.isFinite(v) && v >= 1)
+            return v;
+    }
+    catch {
+        // fall through to default
+    }
+    return 2;
+}
+function resolveShortIdToTaskId(arg, repoRoot) {
+    const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+    if (!fs.existsSync(scriptPath)) {
+        throw new Error(`task-short-id.js not found at ${scriptPath}`);
+    }
+    const result = spawnSync('node', [scriptPath, 'resolve', arg], {
+        encoding: 'utf8',
+        cwd: repoRoot
+    });
+    if (result.status !== 0) {
+        throw new Error((result.stderr || '').trim() || `failed to resolve '${arg}'`);
+    }
+    return result.stdout.trim();
+}
+function listSortedNumeric(dir, width) {
+    if (!fs.existsSync(dir))
+        return [];
+    const pattern = new RegExp(`^\\d{${width}}$`);
+    return fs
+        .readdirSync(dir)
+        .filter((entry) => pattern.test(entry))
+        .sort()
+        .reverse();
+}
+function findInArchive(repoRoot, taskId) {
+    // archive-tasks SKILL writes to .agents/workspace/archive/YYYY/MM/DD/{taskId}/task.md
+    // where YYYY/MM/DD comes from completed_at (or updated_at fallback) — NOT from
+    // the task id's creation date. So we cannot derive the path from taskId alone;
+    // walk the bounded YYYY/MM/DD tree instead. Newest-first to favor recent archives.
+    const archiveDir = path.join(repoRoot, '.agents', 'workspace', 'archive');
+    for (const year of listSortedNumeric(archiveDir, 4)) {
+        const yearDir = path.join(archiveDir, year);
+        for (const month of listSortedNumeric(yearDir, 2)) {
+            const monthDir = path.join(yearDir, month);
+            for (const day of listSortedNumeric(monthDir, 2)) {
+                const candidate = path.join(monthDir, day, taskId, 'task.md');
+                if (fs.existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    return null;
+}
+function findTaskMd(repoRoot, taskId) {
+    for (const sub of FLAT_WORKSPACE_DIRS) {
+        const candidate = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+        if (fs.existsSync(candidate))
+            return candidate;
+    }
+    return findInArchive(repoRoot, taskId);
+}
+function show(args = []) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        if (args.length === 0)
+            process.exitCode = 1;
+        return;
+    }
+    const repoRoot = detectRepoRoot();
+    const arg = args[0];
+    let taskId;
+    if (TASK_ID_RE.test(arg)) {
+        taskId = arg;
+    }
+    else {
+        const shortIdLength = readShortIdLength(repoRoot);
+        const normalized = normalizeShortIdInput(arg, { shortIdLength });
+        if (normalized.kind === 'error') {
+            process.stderr.write(`ai task show: ${normalized.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        if (normalized.kind === 'pass') {
+            process.stderr.write(`ai task show: '${arg}' is not a valid short id or TASK-id; ` +
+                `expected bare digits, '#N', or 'TASK-YYYYMMDD-HHMMSS'\n`);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            taskId = resolveShortIdToTaskId(normalized.value, repoRoot);
+        }
+        catch (e) {
+            process.stderr.write(`ai task show: ${e.message}\n`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const taskMdPath = findTaskMd(repoRoot, taskId);
+    if (!taskMdPath) {
+        process.stderr.write(`ai task show: task ${taskId} not found in active / blocked / completed / archive\n`);
+        process.exitCode = 1;
+        return;
+    }
+    process.stdout.write(fs.readFileSync(taskMdPath, 'utf8'));
+}
+export { show };
+//# sourceMappingURL=show.js.map

package/dist/lib/task/frontmatter.js

@@ -0,0 +1,32 @@
+function parseTaskFrontmatter(content) {
+    const result = {};
+    if (!content.startsWith('---'))
+        return result;
+    const end = content.indexOf('\n---', 3);
+    if (end === -1)
+        return result;
+    const body = content.slice(3, end);
+    for (const rawLine of body.split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        if (!line.trim())
+            continue;
+        const colon = line.indexOf(':');
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        const value = line.slice(colon + 1).trim();
+        if (key)
+            result[key] = value;
+    }
+    return result;
+}
+function extractTitle(content) {
+    for (const line of content.split('\n')) {
+        const m = /^#\s+(?:任务[:：]?\s*)?(.+)$/.exec(line.trim());
+        if (m && m[1])
+            return m[1].trim();
+    }
+    return '';
+}
+export { parseTaskFrontmatter, extractTitle };
+//# sourceMappingURL=frontmatter.js.map

package/dist/lib/task/index.js

@@ -0,0 +1,41 @@
+const USAGE = `Usage: ai task <command> [options]
+
+Commands:
+  ls [--all | --blocked | --completed]   List tasks (default: active)
+  show <N | #N | TASK-id>                Print a task.md
+
+Examples:
+  ai task ls
+  ai task show 11
+  ai task show TASK-20260612-162737
+
+Run 'ai task <command> --help' for details.`;
+export async function runTask(args) {
+    const [subcommand, ...rest] = args;
+    if (!subcommand) {
+        process.stdout.write(`${USAGE}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    if (subcommand === '--help' || subcommand === '-h' || subcommand === 'help') {
+        process.stdout.write(`${USAGE}\n`);
+        return;
+    }
+    switch (subcommand) {
+        case 'ls': {
+            const { ls } = await import("./commands/ls.js");
+            ls(rest);
+            break;
+        }
+        case 'show': {
+            const { show } = await import("./commands/show.js");
+            show(rest);
+            break;
+        }
+        default:
+            process.stderr.write(`Unknown task command: ${subcommand}\n\n`);
+            process.stdout.write(`${USAGE}\n`);
+            process.exitCode = 1;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/lib/task/short-id.js

@@ -0,0 +1,90 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const REGISTRY_NAME = '.short-ids.json';
+function normalizeShortIdInput(input, opts) {
+    const L = opts.shortIdLength;
+    const m = /^#?(\d+)$/.exec(input);
+    if (!m) {
+        return { kind: 'pass', value: input };
+    }
+    const n = Number(m[1]);
+    if (n === 0) {
+        return {
+            kind: 'error',
+            message: `short id '${input}' is invalid (#${'0'.repeat(L)} is reserved)`
+        };
+    }
+    const max = Math.pow(10, L) - 1;
+    if (n > max) {
+        return {
+            kind: 'error',
+            message: `short id ${n} exceeds shortIdLength=${L} capacity (max=${max}); archive tasks or raise task.shortIdLength in .agents/.airc.json`
+        };
+    }
+    return { kind: 'shortId', value: `#${String(n).padStart(L, '0')}` };
+}
+function readRegistry(repoRoot) {
+    const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+    if (!fs.existsSync(registryPath))
+        return null;
+    try {
+        const raw = fs.readFileSync(registryPath, 'utf8');
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== 'object' || !data.ids)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function readBranchFromTaskMd(repoRoot, taskId) {
+    const taskMdPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+    if (!fs.existsSync(taskMdPath))
+        return null;
+    const content = fs.readFileSync(taskMdPath, 'utf8');
+    const m = content.match(/^branch:\s*(.+)$/m);
+    if (!m || !m[1])
+        return null;
+    return m[1].trim().replace(/^(["'])(.*)\1$/, '$2');
+}
+function loadShortIdByTaskId(repoRoot) {
+    const registry = readRegistry(repoRoot);
+    const map = new Map();
+    if (!registry)
+        return map;
+    for (const [key, taskId] of Object.entries(registry.ids)) {
+        map.set(taskId, `#${key}`);
+    }
+    return map;
+}
+/**
+ * Resolve a branch to its active-task short id (`#NN`), or `null` when no
+ * active task is bound to that branch.
+ *
+ * Two-state semantics: this only consults the active registry
+ * (`active/.short-ids.json`) plus each `active/{taskId}/task.md`. Tasks moved
+ * to completed/blocked/cancelled/archive have already released their short id,
+ * so their branches return `null` — in `ai sandbox ls` that surfaces as `-`,
+ * meaning the sandbox is free to remove.
+ */
+function lookupShortIdByBranch(branch, repoRoot, _opts) {
+    const registry = readRegistry(repoRoot);
+    if (!registry)
+        return null;
+    const matches = [];
+    for (const [key, taskId] of Object.entries(registry.ids)) {
+        const taskBranch = readBranchFromTaskMd(repoRoot, taskId);
+        if (taskBranch && taskBranch === branch) {
+            matches.push(`#${key}`);
+        }
+    }
+    if (matches.length === 0)
+        return null;
+    if (matches.length > 1) {
+        process.stderr.write(`Warning: branch '${branch}' is bound to multiple active tasks: ${matches.join(', ')}; using ${matches[0]}\n`);
+    }
+    return matches[0];
+}
+export { normalizeShortIdInput, lookupShortIdByBranch, loadShortIdByTaskId };
+//# sourceMappingURL=short-id.js.map

package/dist/lib/update.js

@@ -7,6 +7,24 @@ import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from "./builtin-tuis.js"
 const defaults = JSON.parse(fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8'));
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');
+// One-time migration of the legacy project-level PR switch to the three-state
+// `prFlow` preference. `true` (the old default / "PR flow on") maps to the
+// strong constraint `required`; `false` maps to `disabled`. A missing or
+// already-migrated config is left untouched (idempotent). Returns the new
+// prFlow value when a migration happened, otherwise null.
+function migratePrFlow(config) {
+    if (config.requiresPullRequest === true) {
+        delete config.requiresPullRequest;
+        config.prFlow = 'required';
+        return 'required';
+    }
+    if (config.requiresPullRequest === false) {
+        delete config.requiresPullRequest;
+        config.prFlow = 'disabled';
+        return 'disabled';
+    }
+    return null;
+}
 function isPathOwnedByOtherPlatform(relativePath, platformType) {
     const top = String(relativePath || '').replace(/\\/g, '/').replace(/^\.\//, '').split('/')[0] ?? '';
     if (!top.startsWith('.'))
@@ -134,7 +152,7 @@ async function cmdUpdate() {
     const sandboxAdded = !config.sandbox;
     const taskAdded = !config.task;
     const labelsAdded = !config.labels;
-    const requiresPullRequestAdded = config.requiresPullRequest === undefined;
+    const prFlowMigrated = migratePrFlow(config);
     let configChanged = changed;
     if (platformAdded) {
         config.platform = structuredClone(defaults.platform);
@@ -152,8 +170,7 @@ async function cmdUpdate() {
         config.labels = structuredClone(defaults.labels);
         configChanged = true;
     }
-    if (requiresPullRequestAdded) {
-        config.requiresPullRequest = defaults.requiresPullRequest;
+    if (prFlowMigrated) {
         configChanged = true;
     }
     if (configChanged) {
@@ -167,7 +184,7 @@ async function cmdUpdate() {
                 ok(`  merged: ${entry}`);
             }
         }
-        else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || requiresPullRequestAdded) {
+        else if (platformAdded || sandboxAdded || taskAdded || labelsAdded || prFlowMigrated) {
             if (platformAdded) {
                 info(`Default platform config added to ${CONFIG_PATH}.`);
             }
@@ -180,8 +197,8 @@ 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}.`);
+            if (prFlowMigrated) {
+                info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
             }
         }
         else {
@@ -199,8 +216,8 @@ 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}.`);
+        if (hasNewEntries && prFlowMigrated) {
+            info(`Migrated legacy requiresPullRequest to prFlow="${prFlowMigrated}" in ${CONFIG_PATH}.`);
         }
         fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', 'utf8');
         ok(`Updated ${CONFIG_PATH}`);

package/lib/defaults.json

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

package/lib/init.ts

@@ -32,7 +32,6 @@ type Defaults = {
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
   labels: Record<string, unknown>;
-  requiresPullRequest: boolean;
 };
 
 type AgentConfig = {
@@ -40,7 +39,6 @@ type AgentConfig = {
   org: string;
   language: string;
   platform: { type: string };
-  requiresPullRequest: boolean;
   templateVersion: string;
   sandbox: Record<string, unknown>;
   task: { shortIdLength: number };
@@ -224,13 +222,6 @@ 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(
@@ -324,7 +315,6 @@ async function cmdInit(): Promise<void> {
     org: orgName,
     language,
     platform: { type: platformType },
-    requiresPullRequest,
     templateVersion: VERSION,
     sandbox: structuredClone(defaults.sandbox),
     task: structuredClone(defaults.task),

package/lib/sandbox/commands/create.ts

@@ -868,13 +868,22 @@ export function ensureCodexModelInheritance(toolDir: string, hostHomeDir?: strin
     }
   }
 
+  const inheritSpecs: Array<readonly [string, 'string' | 'number']> = [
+    ['model', 'string'],
+    ['model_reasoning_effort', 'string'],
+    ['model_auto_compact_token_limit', 'number']
+  ];
+
   let changed = false;
-  for (const key of ['model', 'model_reasoning_effort']) {
+  for (const [key, type] of inheritSpecs) {
     if (Object.hasOwn(sandboxParsed, key)) {
       continue;
     }
     const value = hostParsed[key];
-    if (typeof value !== 'string' || value === '') {
+    if (type === 'string' && (typeof value !== 'string' || value === '')) {
+      continue;
+    }
+    if (type === 'number' && (typeof value !== 'number' || !Number.isFinite(value) || value <= 0)) {
       continue;
     }
     sandboxParsed[key] = value;

package/lib/sandbox/commands/enter.ts

@@ -1,5 +1,10 @@
 import { loadConfig } from '../config.ts';
-import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.ts';
+import {
+  assertValidBranchName,
+  containerNameCandidates,
+  sandboxBranchLabel,
+  sandboxLabel
+} from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import {
   formatCredentialWarnings,
@@ -8,17 +13,23 @@ import {
   redactCommandError,
   validateClaudeCredentialsEnvOverride
 } from '../credentials.ts';
-import { runInteractiveEngine, runSafeEngine } from '../shell.ts';
-import { resolveTaskBranch } from '../task-resolver.ts';
+import { runInteractiveEngine } from '../shell.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 | 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.`;
+import {
+  fetchSandboxRows,
+  resolveBranchArg,
+  selectSandboxContainer,
+  startSandboxContainer
+} from './list-running.ts';
+
+const USAGE = `Usage: ai sandbox exec <branch | TASK-id | N | '#N'> [cmd...]
+
+N (bare) and '#N' both reference the same active task short id from
+.agents/workspace/active/.short-ids.json. They resolve only via that
+registry — they do not reference a container's row position in
+'ai sandbox ls' output.`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
@@ -120,20 +131,29 @@ export async function enter(args: string[]): Promise<number> {
   validateClaudeCredentialsEnvOverride();
   const engine = detectEngine(config);
   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);
-  }
+  const branch = resolveBranchArg(firstArg, { repoRoot: config.repoRoot });
   assertValidBranchName(branch);
-  const running = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
-  const container = containerNameCandidates(config, branch).find((name) => running.includes(name));
 
-  if (!container) {
-    throw new Error(`No running sandbox found for branch '${branch}'`);
+  const { running, nonRunning } = fetchSandboxRows(
+    engine,
+    sandboxLabel(config),
+    sandboxBranchLabel(config)
+  );
+  const found = selectSandboxContainer(
+    [...running, ...nonRunning],
+    containerNameCandidates(config, branch)
+  );
+
+  if (!found) {
+    throw new Error(
+      `No sandbox found for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`
+    );
+  }
+  if (!found.running) {
+    process.stderr.write(`Sandbox '${found.name}' is stopped; starting it...\n`);
+    startSandboxContainer(engine, found.name);
   }
+  const container = found.name;
 
   if (config.tools.includes('claude-code')) {
     try {