@fitlab-ai/agent-infra 0.7.2 → 0.7.3

package/README.md

@@ -165,6 +165,9 @@ curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.
 **Option C - Homebrew (macOS)**
 
 ```bash
+# Newer Homebrew refuses to load formulae from third-party taps until trusted,
+# which silently blocks upgrades. Trust the tap once before installing.
+brew trust fitlab-ai/tap
 brew install fitlab-ai/tap/agent-infra
 ```
 
@@ -218,6 +221,8 @@ The sandbox image also preinstalls `gh`. When `gh auth token` succeeds on the ho
 
 `ai sandbox exec` also forwards a small terminal-detection whitelist (`TERM_PROGRAM`, `TERM_PROGRAM_VERSION`, `LC_TERMINAL`, `LC_TERMINAL_VERSION`) into the container. This keeps interactive TUIs aligned with the host terminal for behaviors such as Claude Code's Shift+Enter newline support, without passing through the full host environment.
 
+`ai sandbox start <branch | TASK-id | N | '#N'>` recovers a sandbox container that has stopped — for example after the host Docker daemon was restarted or replaced (a common case is installing OrbStack over an existing Docker), which leaves the container `Exited`. It only starts a container that already exists and is stopped; if none exists it points you to `ai sandbox create`, and a container that is already running is left untouched. `ai sandbox exec <branch>` performs the same recovery automatically: when the target container exists but is stopped, it starts the container first and then enters it. Because each worktree and per-AI state directory is persisted on the host, restarting a stopped container is safe and loses no data.
+
 On macOS, interactive `ai sandbox exec <branch>` sessions can bridge image paste into the sandbox. When you press `Ctrl+V` and the host clipboard currently holds an image, agent-infra reads the image from the host clipboard, writes a PNG under `~/.agent-infra/clipboard/`, and injects the container path as bracketed paste so Claude Code, Codex, Gemini CLI, and OpenCode can attach it. The host clipboard is only read, never rewritten. The bridge is best-effort: existing sandboxes must be rebuilt to receive the `/clipboard` mount, and if the optional pty dependency or clipboard probe is unavailable the session falls back to the normal interactive path. Set `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` to skip the bridge and enter the normal interactive path directly when diagnosing mouse, scrolling, or other input issues.
 
 When you run the sandbox from a remote Mac over SSH, use `ai cp <ssh-alias>` on the Mac in front of you to push the local clipboard image to that remote Mac first. Copy an image with Cmd+C, run `ai cp mini`, then return to the existing SSH session and press `Ctrl+V`; the sandbox bridge reads the remote Mac's NSPasteboard and injects the image as usual. This command handles PNG images only and uses non-interactive ssh/scp with key-based authentication. For now both the sender and the remote must be macOS—the remote NSPasteboard is written via `osascript`—but the remote-write step is the natural extension point for other platforms later.
@@ -484,7 +489,7 @@ These configurations are not actively tested in this release:
 
 - **Podman** instead of Docker: Works on Fedora 40+ and other `dnf`-based RHEL family distros (RHEL, CentOS Stream, Rocky, Alma) via the `podman-docker` shim (`sudo dnf install podman podman-docker`; optionally `sudo touch /etc/containers/nodocker` to silence its per-command notice).
 - **SELinux-enforcing** hosts (Fedora / RHEL): `ai sandbox create` automatically labels bind mounts with Docker's shared `:z` flag — no setup required. Set `AGENT_INFRA_SELINUX_DISABLE=1` to opt out for debugging.
-- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox refresh`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm`, and `ai sandbox prune` directly.
+- `ai sandbox vm` is a no-op on Linux. Linux uses native Docker directly with no VM to manage; use `ai sandbox create`, `ai sandbox exec`, `ai sandbox start`, `ai sandbox refresh`, `ai sandbox ls`, `ai sandbox rebuild`, `ai sandbox rm`, and `ai sandbox prune` directly.
 
 ### Windows
 
@@ -560,6 +565,7 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 | Skill | Description | Parameters | Recommended use case |
 |-------|-------------|------------|----------------------|
 | `create-pr` | Open a Pull Request to an inferred or explicit target branch. | `task-id` (optional), `target-branch` (optional) | Publish reviewed changes for merge, with optional explicit task linkage after a fresh session. |
+| `watch-pr` | Watch a PR's required checks and self-heal failures until green. | `task-id` or `--pr <number>` (optional; defaults to the current branch's PR) | Monitor CI after create-pr and auto-fix simple failures before merging. |
 
 <a id="code-quality"></a>
 

package/README.zh-CN.md

@@ -19,7 +19,7 @@
   <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D22-brightgreen?logo=node.js" alt="Node.js >= 22"></a>
   <a href="https://github.com/fitlab-ai/agent-infra/releases"><img src="https://img.shields.io/github/v/release/fitlab-ai/agent-infra" alt="GitHub release"></a>
   <a href="https://codecov.io/gh/fitlab-ai/agent-infra"><img src="https://codecov.io/gh/fitlab-ai/agent-infra/graph/badge.svg" alt="codecov"></a>
-  <a href="CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
+  <a href="CONTRIBUTING.zh-CN.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
 </p>
 
 <p align="center">
@@ -165,6 +165,9 @@ curl -fsSL https://raw.githubusercontent.com/fitlab-ai/agent-infra/main/install.
 **方式 C - Homebrew (macOS)**
 
 ```bash
+# 新版 Homebrew 默认拒绝加载第三方 tap 的 formula，
+# 会导致升级被静默跳过。首次安装前先信任本 tap。
+brew trust fitlab-ai/tap
 brew install fitlab-ai/tap/agent-infra
 ```
 
@@ -218,6 +221,8 @@ CLI 会收集项目元数据，向所有支持的 AI TUI 安装 `update-agent-in
 
 `ai sandbox exec` 也会向容器透传一小组终端检测白名单变量（`TERM_PROGRAM`、`TERM_PROGRAM_VERSION`、`LC_TERMINAL`、`LC_TERMINAL_VERSION`）。这样可以让交互式 TUI 保持与宿主终端一致的行为，例如 Claude Code 的 `Shift+Enter` 换行支持，同时避免把整个宿主环境灌入容器。
 
+`ai sandbox start <branch | TASK-id | N | '#N'>` 用于恢复已停止的沙箱容器——典型场景是宿主机 Docker daemon 被重启或替换（例如在已有 Docker 上安装 OrbStack 接管），导致容器变成 `Exited`。它只启动「已存在且已停止」的容器；容器不存在时会提示改用 `ai sandbox create`，已在运行的容器则保持不动。`ai sandbox exec <branch>` 会自动执行同样的恢复：当目标容器存在但已停止时，先启动容器再进入。由于每个 worktree 和各 AI 的 state 目录都持久化在宿主机，重启已停止的容器是安全的，不会丢失数据。
+
 在 macOS 上，交互式 `ai sandbox exec <branch>` 会尽力桥接宿主图片粘贴。当你按下 `Ctrl+V` 且宿主剪贴板当前是图片时，agent-infra 会从宿主剪贴板读取图片，将 PNG 写到 `~/.agent-infra/clipboard/`，再以 bracketed paste 注入容器内路径，让 Claude Code、Codex、Gemini CLI 和 OpenCode 按图片附件处理。宿主剪贴板只读，不会被改写。该能力会自动降级：已有沙箱需要重建后才有 `/clipboard` 挂载；如果可选 pty 依赖或剪贴板探测不可用，会回退到原本的交互进入方式。排查鼠标、滚动或其他输入异常时，可以设置 `AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1` 跳过桥接，直接进入原本的交互路径。
 
 当你通过 SSH 在远端 Mac 上运行沙箱时，可先在手边这台 Mac 上执行 `ai cp <ssh-alias>`，把本机剪贴板图片推送到远端 Mac。典型流程是：Cmd+C 复制图片，运行 `ai cp mini`，回到已有 SSH session 后按 `Ctrl+V`；沙箱桥会读取远端 Mac 的 NSPasteboard，并按原路径注入图片。该命令只处理 PNG 图片，并使用基于 ssh key 的非交互 ssh/scp。目前发送端与远端都需为 macOS（远端通过 `osascript` 写入 NSPasteboard），后续可扩展支持其他远端平台。
@@ -457,7 +462,7 @@ Rootless 模式的已知差异：
 
 - 用 **Podman** 替代 Docker：Fedora 40+ 及其他 `dnf` 系 RHEL 发行版（RHEL、CentOS Stream、Rocky、Alma）上通过 `podman-docker` shim 已可使用（`sudo dnf install podman podman-docker`；可选 `sudo touch /etc/containers/nodocker` 抑制 podman 在每条命令前打印的提示）。
 - **SELinux enforcing** 宿主机（Fedora / RHEL）：`ai sandbox create` 会自动给 bind mount 加 Docker 共享 `:z` 标签，无需手动准备。如需排障可设 `AGENT_INFRA_SELINUX_DISABLE=1` 关闭。
-- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox refresh`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`、`ai sandbox prune`。
+- `ai sandbox vm` 在 Linux 上是空操作。Linux 直接使用 native Docker，没有 VM 需要管理；请直接使用 `ai sandbox create`、`ai sandbox exec`、`ai sandbox start`、`ai sandbox refresh`、`ai sandbox ls`、`ai sandbox rebuild`、`ai sandbox rm`、`ai sandbox prune`。
 
 ### Windows
 
@@ -533,6 +538,7 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 | Skill | 描述 | 参数 | 推荐场景 |
 |-------|------|------|---------|
 | `create-pr` | 向推断出的目标分支或显式指定分支创建 Pull Request。 | `task-id`（可选）、`target-branch`（可选） | 变更准备合入时创建 PR；清空上下文后也可显式传入任务关联。 |
+| `watch-pr` | 监控 PR 的 required checks，失败时自愈直到全绿。 | `task-id` 或 `--pr <number>`（可选；默认取当前分支的 PR） | create-pr 后监控 CI，合入前自动修复简单失败。 |
 
 <a id="code-quality"></a>
 
@@ -923,7 +929,7 @@ agent-infra 通过 Git tag 和 GitHub release 使用语义化版本号。当前
 
 ## 参与贡献
 
-开发规范请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
+开发规范请参阅 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。
 
 <a id="license"></a>
 

package/dist/lib/defaults.json

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

package/dist/lib/init.js

@@ -158,8 +158,6 @@ async function cmdInit() {
         info(`Custom platform '${platformType}' selected. Built-in templates are only complete for github;`
             + ` provide matching '.${platformType}.' or generic templates before running update-agent-infra.`);
     }
-    const requiresPRChoice = await select('Require Pull Request flow?', ['yes', 'no'], 'yes');
-    const requiresPullRequest = requiresPRChoice !== 'no';
     let enabledTUIs;
     try {
         enabledTUIs = await multiSelect('Built-in TUI command files to install/manage', BUILTIN_TUI_IDS.map((id) => ({ id, label: BUILTIN_TUI_DISPLAY[id] })));
@@ -220,7 +218,6 @@ async function cmdInit() {
         org: orgName,
         language,
         platform: { type: platformType },
-        requiresPullRequest,
         templateVersion: VERSION,
         sandbox: structuredClone(defaults.sandbox),
         task: structuredClone(defaults.task),

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

@@ -1,13 +1,12 @@
 import { loadConfig } from "../config.js";
-import { assertValidBranchName, containerNameCandidates } from "../constants.js";
+import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from "../constants.js";
 import { detectEngine } from "../engine.js";
 import { formatCredentialWarnings, formatRemaining, reconcileClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from "../credentials.js";
-import { runInteractiveEngine, runSafeEngine } from "../shell.js";
-import { resolveTaskBranch } from "../task-resolver.js";
+import { runInteractiveEngine } from "../shell.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
 import { runInteractiveWithClipboardBridge } from "../clipboard/bridge.js";
 import { detectHostTimezone } from "../host-timezone.js";
-import { isTaskShortRef, resolveTaskShortRef } from "./list-running.js";
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, startSandboxContainer } from "./list-running.js";
 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
@@ -86,19 +85,18 @@ export async function enter(args) {
     validateClaudeCredentialsEnvOverride();
     const engine = detectEngine(config);
     const [firstArg = '', ...cmd] = args;
-    let branch;
-    if (isTaskShortRef(firstArg)) {
-        branch = resolveTaskShortRef(firstArg, { 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 {
             // Scan all projects so a refresh from a neighbouring sandbox can still flow back to the host.

package/dist/lib/sandbox/commands/list-running.js

@@ -1,7 +1,8 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { runSafeEngine } from "../shell.js";
+import { runSafeEngine, runVerboseEngine } from "../shell.js";
+import { resolveTaskBranch } from "../task-resolver.js";
 export function containerListFormat() {
     return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
 }
@@ -139,4 +140,38 @@ export function resolveTaskShortRef(arg, ctx) {
         `'#N' and bare N resolve only via the registry (not by row position in 'ai sandbox ls'); ` +
         `use a task short id (e.g. 'ai sandbox exec 11'), a TASK-id, or a branch name.`);
 }
+/**
+ * Resolve a sandbox command argument (`<branch | TASK-id | N | '#N'>`) to a
+ * branch name, mirroring `ai sandbox exec` so that `start` and `exec` share one
+ * input contract. Short refs go through the registry-only resolver (which throws
+ * an actionable error on a miss); everything else flows through resolveTaskBranch
+ * (plain branch names pass through unchanged, TASK-ids resolve via task.md).
+ * Callers still run assertValidBranchName on the result.
+ */
+export function resolveBranchArg(arg, ctx) {
+    return isTaskShortRef(arg)
+        ? resolveTaskShortRef(arg, ctx)
+        : resolveTaskBranch(arg, ctx.repoRoot);
+}
+/**
+ * Pick the sandbox container row whose name matches one of the candidate
+ * container names (covers both the '..' and legacy '-' branch sanitizations).
+ * Pure: no IO. Returns null when no row matches.
+ */
+export function selectSandboxContainer(rows, candidates) {
+    return rows.find((row) => candidates.includes(row.name)) ?? null;
+}
+/**
+ * Start an existing (stopped) sandbox container by name. Throws a distinct,
+ * actionable error when `docker start` fails, so callers can tell "start failed"
+ * apart from "container not found".
+ */
+export function startSandboxContainer(engine, name) {
+    try {
+        runVerboseEngine(engine, 'docker', ['start', name]);
+    }
+    catch (error) {
+        throw new Error(`Failed to start sandbox container '${name}': ${error instanceof Error ? error.message : 'unknown error'}`);
+    }
+}
 //# sourceMappingURL=list-running.js.map

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

@@ -16,10 +16,12 @@ Lists all containers for the current project. The '#' column is a
 display-only row number; the 'SHORT' column shows the active task short
 id bound to each container's branch (via
 .agents/workspace/active/.short-ids.json), or '-' if no active task is
-bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').`;
+bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
+A '-' means no active task is bound to that branch, so the sandbox is free
+to remove with "ai sandbox rm <branch>".`;
 const CONTAINER_TABLE_HEADERS = ['#', 'SHORT', 'NAMES', 'STATUS', 'BRANCH'];
-export function formatContainerTable(rows) {
-    return formatTable(CONTAINER_TABLE_HEADERS, rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch]));
+export function formatContainerTable(rows, zebra = false) {
+    return formatTable(CONTAINER_TABLE_HEADERS, rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch]), { zebra });
 }
 function listChildren(dir) {
     if (!fs.existsSync(dir)) {
@@ -54,10 +56,13 @@ export function ls(args = []) {
                 branch: container.branch
             };
         });
-        for (const line of formatContainerTable(tableRows)) {
+        for (const line of formatContainerTable(tableRows, Boolean(process.stdout.isTTY))) {
             process.stdout.write(`  ${line}\n`);
         }
         process.stdout.write(`  Total: ${ordered.length} containers\n`);
+        if (tableRows.some((r) => r.shortId === '-')) {
+            process.stdout.write(`  SHORT '-' = no active task bound; that sandbox is free to remove with 'ai sandbox rm <branch>'.\n`);
+        }
     }
     p.log.step('Worktrees');
     const worktrees = listChildren(config.worktreeBase);

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

@@ -0,0 +1,36 @@
+import { loadConfig } from "../config.js";
+import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from "../constants.js";
+import { detectEngine } from "../engine.js";
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, startSandboxContainer } from "./list-running.js";
+const USAGE = `Usage: ai sandbox start <branch | TASK-id | N | '#N'>
+
+Start an existing sandbox container that has stopped (for example after the
+Docker daemon was restarted or replaced). The container must already exist:
+if none is found, run 'ai sandbox create <branch>' first. A container that is
+already running is left untouched.`;
+export async function start(args) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(`${USAGE}\n`);
+        if (args.length === 0) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    const [firstArg = ''] = args;
+    const config = loadConfig();
+    const engine = detectEngine(config);
+    const branch = resolveBranchArg(firstArg, { repoRoot: config.repoRoot });
+    assertValidBranchName(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 container for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`);
+    }
+    if (found.running) {
+        process.stdout.write(`Sandbox '${found.name}' is already running.\n`);
+        return;
+    }
+    startSandboxContainer(engine, found.name);
+    process.stdout.write(`Started sandbox '${found.name}'.\n`);
+}
+//# sourceMappingURL=start.js.map

package/dist/lib/sandbox/index.js

@@ -6,6 +6,9 @@ Commands:
                                Enter sandbox or run a command. N (bare) is the
                                recommended form for task short ids (e.g.
                                'ai sandbox exec 11'); '#N' is also accepted.
+  start <branch | TASK-id | N | '#N'>
+                               Start an existing stopped sandbox container
+                               (e.g. after the Docker daemon restarted)
   ls                           List sandboxes for the current project (the '#'
                                column is a display-only row number; the 'SHORT'
                                column shows the active task short id, '-' if none)
@@ -50,6 +53,11 @@ export async function runSandbox(args) {
             }
             break;
         }
+        case 'start': {
+            const { start } = await import("./commands/start.js");
+            await start(rest);
+            break;
+        }
         case 'ls': {
             const { ls } = await import("./commands/ls.js");
             ls(rest);

package/dist/lib/table.js

@@ -1,4 +1,6 @@
-function formatTable(headers, rows) {
+import pc from 'picocolors';
+function formatTable(headers, rows, options = {}) {
+    const { zebra = false } = options;
     const columnCount = headers.length;
     const widths = headers.map((header, i) => {
         const headerLen = header.length;
@@ -23,7 +25,14 @@ function formatTable(headers, rows) {
         }
         return parts.join('  ').trimEnd();
     };
-    return [renderRow(headers), ...rows.map((row) => renderRow(row))];
+    const dataLines = rows.map((row, i) => {
+        const line = renderRow(row);
+        // Zebra stripes: dim even-numbered data rows (rows 2, 4, 6... -> 0-based
+        // odd index). The header and odd rows are left untouched. When zebra is
+        // off, pc.dim is never called, so the output is byte-identical to before.
+        return zebra && i % 2 === 1 ? pc.dim(line) : line;
+    });
+    return [renderRow(headers), ...dataLines];
 }
 export { formatTable };
 //# sourceMappingURL=table.js.map

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

@@ -113,7 +113,7 @@ function ls(args = []) {
         r.branch,
         r.title
     ]);
-    for (const line of formatTable(TABLE_HEADERS, tableRows)) {
+    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`);

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

@@ -58,6 +58,16 @@ function loadShortIdByTaskId(repoRoot) {
     }
     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)

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/enter.ts

@@ -1,5 +1,10 @@
 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,
@@ -8,12 +13,16 @@ 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 { isTaskShortRef, resolveTaskShortRef } from './list-running.ts';
+import {
+  fetchSandboxRows,
+  resolveBranchArg,
+  selectSandboxContainer,
+  startSandboxContainer
+} from './list-running.ts';
 
 const USAGE = `Usage: ai sandbox exec <branch | TASK-id | N | '#N'> [cmd...]
 
@@ -122,19 +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)) {
-    branch = resolveTaskShortRef(firstArg, { 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 {

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

@@ -1,7 +1,8 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { runSafeEngine } from '../shell.ts';
+import { runSafeEngine, runVerboseEngine } from '../shell.ts';
+import { resolveTaskBranch } from '../task-resolver.ts';
 
 export type SandboxRow = {
   name: string;
@@ -172,3 +173,44 @@ export function resolveTaskShortRef(
       `use a task short id (e.g. 'ai sandbox exec 11'), a TASK-id, or a branch name.`
   );
 }
+
+/**
+ * Resolve a sandbox command argument (`<branch | TASK-id | N | '#N'>`) to a
+ * branch name, mirroring `ai sandbox exec` so that `start` and `exec` share one
+ * input contract. Short refs go through the registry-only resolver (which throws
+ * an actionable error on a miss); everything else flows through resolveTaskBranch
+ * (plain branch names pass through unchanged, TASK-ids resolve via task.md).
+ * Callers still run assertValidBranchName on the result.
+ */
+export function resolveBranchArg(arg: string, ctx: { repoRoot: string }): string {
+  return isTaskShortRef(arg)
+    ? resolveTaskShortRef(arg, ctx)
+    : resolveTaskBranch(arg, ctx.repoRoot);
+}
+
+/**
+ * Pick the sandbox container row whose name matches one of the candidate
+ * container names (covers both the '..' and legacy '-' branch sanitizations).
+ * Pure: no IO. Returns null when no row matches.
+ */
+export function selectSandboxContainer(
+  rows: SandboxRow[],
+  candidates: string[]
+): SandboxRow | null {
+  return rows.find((row) => candidates.includes(row.name)) ?? null;
+}
+
+/**
+ * Start an existing (stopped) sandbox container by name. Throws a distinct,
+ * actionable error when `docker start` fails, so callers can tell "start failed"
+ * apart from "container not found".
+ */
+export function startSandboxContainer(engine: string, name: string): void {
+  try {
+    runVerboseEngine(engine, 'docker', ['start', name]);
+  } catch (error) {
+    throw new Error(
+      `Failed to start sandbox container '${name}': ${error instanceof Error ? error.message : 'unknown error'}`
+    );
+  }
+}

package/lib/sandbox/commands/ls.ts

@@ -18,7 +18,9 @@ Lists all containers for the current project. The '#' column is a
 display-only row number; the 'SHORT' column shows the active task short
 id bound to each container's branch (via
 .agents/workspace/active/.short-ids.json), or '-' if no active task is
-bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').`;
+bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
+A '-' means no active task is bound to that branch, so the sandbox is free
+to remove with "ai sandbox rm <branch>".`;
 
 const CONTAINER_TABLE_HEADERS = ['#', 'SHORT', 'NAMES', 'STATUS', 'BRANCH'] as const;
 
@@ -30,10 +32,11 @@ type ContainerTableRow = {
   branch: string;
 };
 
-export function formatContainerTable(rows: ContainerTableRow[]): string[] {
+export function formatContainerTable(rows: ContainerTableRow[], zebra = false): string[] {
   return formatTable(
     CONTAINER_TABLE_HEADERS,
-    rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch])
+    rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch]),
+    { zebra }
   );
 }
 
@@ -74,10 +77,15 @@ export function ls(args: string[] = []): void {
         branch: container.branch
       };
     });
-    for (const line of formatContainerTable(tableRows)) {
+    for (const line of formatContainerTable(tableRows, Boolean(process.stdout.isTTY))) {
       process.stdout.write(`  ${line}\n`);
     }
     process.stdout.write(`  Total: ${ordered.length} containers\n`);
+    if (tableRows.some((r) => r.shortId === '-')) {
+      process.stdout.write(
+        `  SHORT '-' = no active task bound; that sandbox is free to remove with 'ai sandbox rm <branch>'.\n`
+      );
+    }
   }
 
   p.log.step('Worktrees');