@fitlab-ai/agent-infra 0.7.7 → 0.8.0

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

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import { formatTable } from "../../table.js";
 import { resolveTaskRef } from "../resolve-ref.js";
+import { parseLedger, HUMAN_DECISION_STATUSES } from "../ledger.js";
 const USAGE = `Usage: ai task log <N | #N | TASK-id>
 
 Renders a task's activity log as a per-step status table. A step's start and
@@ -17,7 +18,6 @@ Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
 const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'];
 // The activity-log H2 heading is language-dependent (zh template / en template).
 const HEADING_RE = /^##\s+(活动日志|Activity Log)\s*$/;
-const LEDGER_HEADING_RE = /^##\s+(审查分歧账本|Review Disagreement Ledger)\s*$/;
 const NEXT_H2_RE = /^##\s/;
 // `- {time} — **{step}** by {agent} — {note}` ; the separator is an em-dash
 // (U+2014). STEP/AGENT are non-greedy so a note that itself contains ' — ' or
@@ -33,7 +33,6 @@ const STARTED_SUFFIX_RE = /\s*\[started\]\s*$/;
 // note these differ from the `.airc.json` long names claude-code/gemini-cli).
 // Any other executor token (a human name, possibly CJK) is treated as human.
 const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'gemini', 'opencode', 'cursor']);
-const HUMAN_DECISION_STATUSES = new Set(['needs-human-decision', 'human-decided']);
 const ENV_BLOCKED_RE = /\(\+\s*(\d+)\s+env-blocked\)/i;
 // Same match plus any leading whitespace, so folding the count into the verdict
 // text drops the redundant `(+ n env-blocked)` fragment without leaving a gap.
@@ -102,30 +101,6 @@ function pairEntries(entries) {
     }
     return rows;
 }
-function parseReviewLedger(content) {
-    const lines = content.split('\n');
-    let i = 0;
-    while (i < lines.length && !LEDGER_HEADING_RE.test(lines[i]))
-        i += 1;
-    if (i >= lines.length)
-        return [];
-    const rows = [];
-    for (let j = i + 1; j < lines.length; j += 1) {
-        if (NEXT_H2_RE.test(lines[j]))
-            break;
-        const line = lines[j].trim();
-        if (!line.startsWith('|'))
-            continue;
-        const cells = line
-            .split('|')
-            .slice(1, -1)
-            .map((cell) => cell.trim());
-        if (cells.length < 6 || cells[0] === 'id' || /^-+$/.test(cells[0] ?? ''))
-            continue;
-        rows.push({ stage: cells[1], status: cells[4] });
-    }
-    return rows;
-}
 function countHumanDecisionsByStage(rows) {
     const counts = new Map();
     for (const row of rows) {
@@ -188,7 +163,7 @@ function log(args = []) {
         return;
     }
     const steps = pairEntries(entries);
-    const humanDecisionCounts = countHumanDecisionsByStage(parseReviewLedger(content));
+    const humanDecisionCounts = countHumanDecisionsByStage(parseLedger(content));
     const rows = steps.map((s, idx) => {
         const stage = reviewStageForStep(s.step);
         const note = stage

package/dist/lib/task/index.js

@@ -2,6 +2,7 @@ const USAGE = `Usage: ai task <command> [options]
 
 Commands:
   cat <ref> <artifact | N>               Print a task artifact (by name or number)
+  decisions, d <ref> [selector]          List human-decision (HD-) items, or show one's detail
   files <ref>                            List artifacts in a task dir (numbered)
   grep <pattern> [ref] [artifact | N]    Literal search across task artifacts (omit ref to scan all)
   issue-body <ref> [--template <path>]   Print a deterministic Issue body from task.md (描述 + 需求, or an Issue Form)
@@ -13,6 +14,8 @@ Commands:
 Examples:
   ai task cat 11 analysis
   ai task cat 11 3
+  ai task decisions 11
+  ai task d 11 HD-3 --format markdown
   ai task files 11
   ai task grep resolveArtifact
   ai task grep resolveArtifact 11
@@ -42,6 +45,12 @@ export async function runTask(args) {
             cat(rest);
             break;
         }
+        case 'decisions':
+        case 'd': {
+            const { decisions } = await import("./commands/decisions.js");
+            decisions(rest);
+            break;
+        }
         case 'files': {
             const { files } = await import("./commands/files.js");
             files(rest);

package/dist/lib/task/ledger.js

@@ -0,0 +1,66 @@
+// Shared parser for the task.md `## 审查分歧账本` (Review Disagreement Ledger).
+// Single source of truth for ledger row parsing across `ai task` commands
+// (log, decisions) — see the plan's D1 constraint "no third parser". The gate
+// parser in `.agents/scripts/validate-artifact.js` is a separate concern and
+// must be kept semantically in sync by hand (noted in review-handshake.md).
+// The ledger H2 heading is language-dependent (zh template / en template).
+const LEDGER_HEADING_RE = /^##\s+(审查分歧账本|Review Disagreement Ledger)\s*$/;
+const NEXT_H2_RE = /^##\s/;
+// Terminal statuses the completion gates treat as resolved.
+const LEDGER_TERMINAL = new Set(['confirmed', 'closed', 'human-decided']);
+// Statuses that represent an executor-raised human-decision row (pending or done).
+const HUMAN_DECISION_STATUSES = new Set(['needs-human-decision', 'human-decided']);
+// Parse all rows of the disagreement ledger table. Skips the heading, the
+// header row (`| id | ... |`) and the `|---|` separator; ignores non-`|` lines.
+// Rows with fewer than 6 columns are skipped (mirrors the JS gate parser).
+function parseLedger(content) {
+    const lines = content.split('\n');
+    let i = 0;
+    while (i < lines.length && !LEDGER_HEADING_RE.test(lines[i]))
+        i += 1;
+    if (i >= lines.length)
+        return [];
+    const rows = [];
+    for (let j = i + 1; j < lines.length; j += 1) {
+        if (NEXT_H2_RE.test(lines[j]))
+            break;
+        const line = lines[j].trim();
+        if (!line.startsWith('|'))
+            continue;
+        const cells = line
+            .split('|')
+            .slice(1, -1)
+            .map((cell) => cell.trim());
+        if (cells.length < 6)
+            continue;
+        if (cells[0] === 'id' || /^-+$/.test(cells[0] ?? ''))
+            continue;
+        rows.push({
+            id: cells[0],
+            stage: cells[1],
+            round: cells[2],
+            severity: cells[3],
+            status: cells[4],
+            evidence: cells[5]
+        });
+    }
+    return rows;
+}
+// Allocate the next globally-unique human-decision id. Scans every `HD-<n>`
+// already present in the ledger (across all stages) and returns `HD-{max+1}`,
+// or `HD-1` when none exist. Global monotonic allocation prevents id collisions
+// across the analysis / plan / code stages (plan PL-2).
+function nextHdId(rows) {
+    let max = 0;
+    for (const row of rows) {
+        const m = /^HD-(\d+)$/.exec(row.id);
+        if (!m)
+            continue;
+        const n = Number.parseInt(m[1], 10);
+        if (n > max)
+            max = n;
+    }
+    return `HD-${max + 1}`;
+}
+export { parseLedger, nextHdId, LEDGER_TERMINAL, HUMAN_DECISION_STATUSES };
+//# sourceMappingURL=ledger.js.map

package/dist/lib/task/sections.js

@@ -40,5 +40,34 @@ function findSectionHeading(content, aliases) {
     }
     return aliases[0];
 }
-export { extractSection, findSectionHeading };
+/**
+ * Return the body of the first `### {headingPrefix}` sub-section, from the
+ * heading line (inclusive) to the next `### ` / `## ` heading or EOF. Used to
+ * pull a single `### HD-N` human-decision detail block out of an artifact. The
+ * prefix must be followed by a word boundary so `HD-1` does not match `HD-10`
+ * (e.g. `### HD-1`, `### HD-1：标题`, `### HD-1 [needs-human-decision]`). Leading
+ * and trailing blank lines are trimmed. Returns '' when no match is present.
+ */
+function extractSubSection(content, headingPrefix) {
+    const lines = content.split('\n');
+    const headRe = new RegExp(`^###\\s+${escapeRegExp(headingPrefix)}(?![\\w-])`);
+    let start = -1;
+    for (let i = 0; i < lines.length; i += 1) {
+        if (headRe.test(lines[i].trim())) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1)
+        return '';
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i += 1) {
+        if (/^###?\s+/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    return lines.slice(start, end).join('\n').replace(/^\n+/, '').replace(/\n+$/, '');
+}
+export { extractSection, findSectionHeading, extractSubSection };
 //# sourceMappingURL=sections.js.map

package/lib/decide.ts

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { VERSION } from './version.ts';
+import { resolveTaskRef } from './task/resolve-ref.ts';
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+
+type DecideOptions = {
+  repoRoot?: string;
+  now?: () => string;
+  version?: string;
+};
+
+function detectRepoRoot(): string {
+  return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  }).trim();
+}
+
+function defaultNow(): string {
+  return new Intl.DateTimeFormat('sv-SE', {
+    timeZoneName: 'longOffset',
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false
+  })
+    .format(new Date())
+    .replace(' GMT', '');
+}
+
+function taskPath(repoRoot: string, ref: string): string {
+  if (!TASK_ID_RE.test(ref)) {
+    const resolved = resolveTaskRef(ref);
+    if (!resolved.ok) throw new Error(resolved.message);
+    if (!resolved.taskDir.includes(`${path.join('.agents', 'workspace', 'active')}${path.sep}`)) {
+      throw new Error(`task ${resolved.taskId} is not active`);
+    }
+    return resolved.taskMdPath;
+  }
+  const candidate = path.join(repoRoot, '.agents', 'workspace', 'active', ref, 'task.md');
+  if (!fs.existsSync(candidate)) throw new Error(`active task not found: ${ref}`);
+  return candidate;
+}
+
+function replaceFrontmatterField(content: string, field: string, value: string): string {
+  const re = new RegExp(`^${field}:.*$`, 'm');
+  if (re.test(content)) return content.replace(re, `${field}: ${value}`);
+  return content.replace(/^---\n/, `---\n${field}: ${value}\n`);
+}
+
+function replaceLedgerRow(content: string, hdId: string): { content: string; found: boolean; pending: boolean } {
+  const lines = content.split('\n');
+  let found = false;
+  let pending = false;
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i] as string;
+    if (!line.trim().startsWith(`| ${hdId} |`)) continue;
+    found = true;
+    const cells = line.split('|').slice(1, -1).map((cell) => cell.trim());
+    if (cells[4] !== 'needs-human-decision') break;
+    pending = true;
+    cells[4] = 'human-decided';
+    cells[5] = `task.md#${hdId}`;
+    lines[i] = `| ${cells.join(' | ')} |`;
+    break;
+  }
+  return { content: lines.join('\n'), found, pending };
+}
+
+function appendUnderHeading(content: string, heading: string, block: string): string {
+  if (!content.includes(`${heading}\n`)) {
+    return `${content.trimEnd()}\n\n${heading}\n\n${block}\n`;
+  }
+  const idx = content.indexOf(`${heading}\n`) + heading.length + 1;
+  const before = content.slice(0, idx);
+  const after = content.slice(idx);
+  return `${before}\n${block}\n${after.replace(/^\n/, '')}`;
+}
+
+export async function decide(args: string[], options: DecideOptions = {}): Promise<number> {
+  const [taskRef, hdId, ...decisionParts] = args;
+  if (!taskRef || !hdId || decisionParts.length === 0) {
+    process.stderr.write('Usage: ai decide <task-ref> <HD-id> <decision>\n');
+    return 1;
+  }
+  try {
+    const repoRoot = options.repoRoot ?? detectRepoRoot();
+    const file = taskPath(repoRoot, taskRef);
+    let content = fs.readFileSync(file, 'utf8');
+    const replaced = replaceLedgerRow(content, hdId);
+    if (!replaced.found) throw new Error(`${hdId} not found in review ledger`);
+    if (!replaced.pending) throw new Error(`${hdId} is not needs-human-decision`);
+    content = replaced.content;
+    const now = (options.now ?? defaultNow)();
+    content = replaceFrontmatterField(content, 'updated_at', now);
+    content = replaceFrontmatterField(content, 'agent_infra_version', options.version ?? VERSION);
+    const decision = decisionParts.join(' ');
+    content = appendUnderHeading(
+      content,
+      '## 人工裁决',
+      `### ${hdId}\n\n- **裁决时间**：${now}\n- **裁决结果**：${decision}`
+    );
+    content = appendUnderHeading(
+      content,
+      '## 活动日志',
+      `- ${now} — **Human Decision** by human — ${hdId} decided`
+    );
+    fs.writeFileSync(file, content);
+    return 0;
+  } catch (error) {
+    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+    return 1;
+  }
+}
+
+export async function cmdDecide(args: string[]): Promise<void> {
+  process.exitCode = await decide(args);
+}

package/lib/run/host.ts

@@ -0,0 +1,47 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+export type RunProcessResult = {
+  exitCode: number | null;
+  signal?: NodeJS.Signals | null;
+  stdout?: string;
+  stderr?: string;
+};
+
+function resolveCommand(file: string): string {
+  if (process.platform !== 'win32' || path.extname(file)) {
+    return file;
+  }
+
+  const pathValue = process.env.Path || process.env.PATH || '';
+  const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const lowerCandidate = path.join(dir, `${file}${extension.toLowerCase()}`);
+      if (fs.existsSync(lowerCandidate)) return lowerCandidate;
+      const upperCandidate = path.join(dir, `${file}${extension.toUpperCase()}`);
+      if (fs.existsSync(upperCandidate)) return upperCandidate;
+    }
+  }
+
+  return file;
+}
+
+function needsShell(file: string): boolean {
+  return process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(file);
+}
+
+export async function runHostCommand(command: string[]): Promise<RunProcessResult> {
+  const [file, ...args] = command;
+  if (!file) throw new Error('run: missing command');
+  return new Promise((resolve, reject) => {
+    const resolvedFile = resolveCommand(file);
+    const child = spawn(resolvedFile, args, {
+      stdio: ['ignore', 'inherit', 'inherit'],
+      shell: needsShell(resolvedFile)
+    });
+    child.on('error', reject);
+    child.on('close', (exitCode, signal) => resolve({ exitCode, signal }));
+  });
+}

package/lib/run/index.ts

@@ -0,0 +1,124 @@
+import { loadServerConfig } from '../server/config.ts';
+import { resolveTaskBranch } from '../sandbox/task-resolver.ts';
+import { runInSandbox } from '../sandbox/capture.ts';
+import { buildTuiCommand, renderPrompt, selectTui } from './tui.ts';
+import { getSkillRunSpec } from './skills.ts';
+import { runHostCommand, type RunProcessResult } from './host.ts';
+
+export type ParsedRunArgs = {
+  skill: string;
+  taskRef: string | null;
+  args: string[];
+  tui: string | null;
+};
+
+export type SandboxRunRequest = {
+  taskRef: string;
+  branch: string;
+  command: string[];
+};
+
+export type RunSkillOptions = {
+  command?: Record<string, unknown>;
+  repoRoot?: string;
+  runHost?: (command: string[]) => Promise<RunProcessResult>;
+  runSandbox?: (request: SandboxRunRequest) => Promise<RunProcessResult>;
+  writeStdout?: (chunk: string) => void;
+  writeStderr?: (chunk: string) => void;
+};
+
+const USAGE = `Usage: ai run <skill> [task-ref] [args...] [--tui <name>]
+
+Examples:
+  ai run create-task "describe the task" --tui codex
+  ai run code-task #7 --tui codex`;
+
+function extractTui(args: string[]): { rest: string[]; tui: string | null } {
+  const rest: string[] = [];
+  let tui: string | null = null;
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i] as string;
+    if (arg === '--tui') {
+      const value = args[i + 1];
+      if (!value) throw new Error('--tui requires a value');
+      tui = value;
+      i += 1;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { rest, tui };
+}
+
+export function parseRunArgs(args: string[]): ParsedRunArgs {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    throw new Error(USAGE);
+  }
+  const { rest, tui } = extractTui(args);
+  const [skill = '', maybeTaskRef, ...remaining] = rest;
+  const spec = getSkillRunSpec(skill);
+  if (!spec) throw new Error(`Unknown skill '${skill}'`);
+  if (spec.kind === 'create') {
+    const createArgs = rest.slice(1);
+    if (createArgs.length === 0) throw new Error('create-task requires a description');
+    return { skill, taskRef: null, args: createArgs, tui };
+  }
+  if (!maybeTaskRef) throw new Error(`${skill} requires a task-ref`);
+  return { skill, taskRef: maybeTaskRef, args: remaining, tui };
+}
+
+function assertAllowedByConfig(skill: string, commandConfig: Record<string, unknown>): void {
+  const allowed = commandConfig.allowedSkills;
+  if (!Array.isArray(allowed)) return;
+  if (!allowed.every((entry) => typeof entry === 'string')) {
+    throw new Error('command.allowedSkills must be an array of skill names');
+  }
+  if (!allowed.includes(skill)) {
+    throw new Error(`Skill '${skill}' is not allowed by command.allowedSkills`);
+  }
+}
+
+export async function runSkill(args: string[], options: RunSkillOptions = {}): Promise<number> {
+  const parsed = parseRunArgs(args);
+  const config = options.command ? null : loadServerConfig({ rootDir: options.repoRoot });
+  const commandConfig = options.command ?? config?.command ?? {};
+  assertAllowedByConfig(parsed.skill, commandConfig);
+  const tui = selectTui(parsed.skill, { cliTui: parsed.tui, command: commandConfig });
+  const promptArgs = parsed.taskRef === null ? parsed.args : [parsed.taskRef, ...parsed.args];
+  const prompt = renderPrompt({ tui, skill: parsed.skill, args: promptArgs });
+  const [file, argv] = buildTuiCommand(tui, prompt);
+  const command = [file, ...argv];
+
+  if (parsed.taskRef === null) {
+    const result = await (options.runHost ?? runHostCommand)(command);
+    return result.exitCode ?? (result.signal ? 1 : 0);
+  }
+
+  const repoRoot = options.repoRoot ?? config?.repoRoot ?? process.cwd();
+  const branch = resolveTaskBranch(parsed.taskRef, repoRoot);
+  const runSandbox = options.runSandbox ?? ((request: SandboxRunRequest) => runInSandbox(request));
+  const result = await runSandbox({ taskRef: parsed.taskRef, branch, command });
+  if (result.stdout) {
+    (options.writeStdout ?? ((chunk: string) => process.stdout.write(chunk)))(result.stdout);
+  }
+  if (result.stderr) {
+    (options.writeStderr ?? ((chunk: string) => process.stderr.write(chunk)))(result.stderr);
+  }
+  return result.exitCode ?? (result.signal ? 1 : 0);
+}
+
+export async function cmdRun(args: string[]): Promise<void> {
+  try {
+    const code = await runSkill(args);
+    process.exitCode = code;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('Usage:')) {
+      process.stdout.write(`${message}\n`);
+      process.exitCode = args.length === 0 ? 1 : 0;
+    } else {
+      process.stderr.write(`Error: ${message}\n`);
+      process.exitCode = 1;
+    }
+  }
+}

package/lib/run/prompt.ts

@@ -0,0 +1 @@
+export { renderPrompt } from './tui.ts';

package/lib/run/skills.ts

@@ -0,0 +1,34 @@
+export type SkillRunSpec =
+  | { kind: 'task'; skill: string; role: 'exec'; requiresSandbox: true }
+  | { kind: 'create'; skill: 'create-task'; role: 'exec'; requiresSandbox: false };
+
+const TASK_SKILLS = new Set([
+  'analyze-task',
+  'block-task',
+  'cancel-task',
+  'code-task',
+  'commit',
+  'complete-task',
+  'create-pr',
+  'plan-task',
+  'review-analysis',
+  'review-code',
+  'review-plan',
+  'test',
+  'test-integration',
+  'watch-pr'
+]);
+
+export function getSkillRunSpec(skill: string): SkillRunSpec | null {
+  if (skill === 'create-task') {
+    return { kind: 'create', skill: 'create-task', role: 'exec', requiresSandbox: false };
+  }
+  if (TASK_SKILLS.has(skill)) {
+    return { kind: 'task', skill, role: 'exec', requiresSandbox: true };
+  }
+  return null;
+}
+
+export function allowedSkillNames(): string[] {
+  return ['create-task', ...TASK_SKILLS].sort();
+}

package/lib/run/tui.ts

@@ -0,0 +1,40 @@
+export type TuiName = 'claude' | 'codex' | 'gemini' | 'opencode';
+
+const TUI_NAMES = new Set(['claude', 'codex', 'gemini', 'opencode']);
+
+export type CommandConfig = {
+  defaultTui?: unknown;
+  skillTuiDefaults?: unknown;
+};
+
+function isTuiName(value: unknown): value is TuiName {
+  return typeof value === 'string' && TUI_NAMES.has(value);
+}
+
+export function selectTui(
+  skill: string,
+  options: { cliTui?: string | null; command?: CommandConfig }
+): TuiName {
+  if (isTuiName(options.cliTui)) return options.cliTui;
+  const defaults = options.command?.skillTuiDefaults;
+  if (defaults && typeof defaults === 'object' && !Array.isArray(defaults)) {
+    const value = (defaults as Record<string, unknown>)[skill];
+    if (isTuiName(value)) return value;
+  }
+  if (isTuiName(options.command?.defaultTui)) return options.command.defaultTui;
+  return 'codex';
+}
+
+export function renderPrompt(params: { tui: TuiName; skill: string; args: string[] }): string {
+  const suffix = [params.skill, ...params.args].join(' ').trim();
+  if (params.tui === 'codex') return `$${suffix}`;
+  if (params.tui === 'gemini') return `/agent-infra:${suffix}`;
+  return `/${suffix}`;
+}
+
+export function buildTuiCommand(tui: TuiName, prompt: string): [string, string[]] {
+  if (tui === 'claude') return ['claude', ['--dangerously-skip-permissions', '--print', prompt]];
+  if (tui === 'gemini') return ['gemini', ['--approval-mode', 'yolo', '--prompt', prompt]];
+  if (tui === 'opencode') return ['opencode', ['run', '--dangerously-skip-permissions', prompt]];
+  return ['codex', ['exec', '--dangerously-bypass-approvals-and-sandbox', prompt]];
+}

package/lib/sandbox/capture.ts

@@ -0,0 +1,84 @@
+import { spawn } from 'node:child_process';
+import { loadConfig } from './config.ts';
+import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.ts';
+import { detectEngine } from './engine.ts';
+import { hostTimezoneEnvFlags, terminalEnvFlags } from './commands/enter.ts';
+import {
+  fetchSandboxRows,
+  selectSandboxContainer,
+  startSandboxContainer,
+  type SandboxRow
+} from './commands/list-running.ts';
+
+export type SandboxCaptureRequest = {
+  taskRef: string;
+  branch: string;
+  command: string[];
+  timeoutMs?: number;
+};
+
+export type SandboxCaptureResult = {
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  stdout: string;
+  stderr: string;
+};
+
+export type SandboxCaptureOptions = {
+  engine?: string;
+  repoRoot?: string;
+  containerCandidates?: string[];
+  rows?: SandboxRow[];
+  startContainer?: (name: string) => void;
+  spawn?: (file: string, args: string[]) => Promise<SandboxCaptureResult>;
+};
+
+async function spawnCapture(file: string, args: string[]): Promise<SandboxCaptureResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', reject);
+    child.on('close', (exitCode, signal) => resolve({ exitCode, signal, stdout, stderr }));
+  });
+}
+
+export async function runInSandbox(
+  request: SandboxCaptureRequest,
+  options: SandboxCaptureOptions = {}
+): Promise<SandboxCaptureResult> {
+  const config = options.engine ? null : loadConfig();
+  const engine = options.engine ?? detectEngine(config!);
+  const rows =
+    options.rows ??
+    (() => {
+      const fetched = fetchSandboxRows(engine, sandboxLabel(config!), sandboxBranchLabel(config!));
+      return [...fetched.running, ...fetched.nonRunning];
+    })();
+  const candidates = options.containerCandidates ?? containerNameCandidates(config!, request.branch);
+  const found = selectSandboxContainer(rows, candidates);
+  if (!found) {
+    throw new Error(
+      `Sandbox for ${request.branch} not found. Create it first with ai sandbox create ${request.taskRef}.`
+    );
+  }
+  if (!found.running) {
+    (options.startContainer ?? ((name: string) => startSandboxContainer(engine, name)))(found.name);
+  }
+  const dockerArgs = [
+    'exec',
+    ...terminalEnvFlags(),
+    ...hostTimezoneEnvFlags(),
+    found.name,
+    ...request.command
+  ];
+  return (options.spawn ?? spawnCapture)('docker', dockerArgs);
+}