@fitlab-ai/agent-infra 0.7.1 → 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/bin/cli.ts

@@ -18,6 +18,7 @@ Usage:
   agent-infra init            Initialize a new project with update-agent-infra seed command
   agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
   agent-infra sandbox         Manage Docker-based AI sandboxes
+  agent-infra task            Read-only views over .agents/workspace tasks (ls / show)
   agent-infra update          Update seed files and sync file registry for an existing project
   agent-infra version         Show version
 
@@ -97,6 +98,16 @@ switch (command) {
     });
     break;
   }
+  case 'task': {
+    const imported = await importCommand('../lib/task/index.ts');
+    if (!imported) break;
+    const { runTask } = imported;
+    await runTask(process.argv.slice(3)).catch((e: unknown) => {
+      process.stderr.write(`Error: ${errorMessage(e)}\n`);
+      process.exit(1);
+    });
+    break;
+  }
   case 'cp': {
     const imported = await importCommand('../lib/cp.ts');
     if (!imported) break;

package/dist/bin/cli.js

@@ -22,6 +22,7 @@ Usage:
   agent-infra init            Initialize a new project with update-agent-infra seed command
   agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
   agent-infra sandbox         Manage Docker-based AI sandboxes
+  agent-infra task            Read-only views over .agents/workspace tasks (ls / show)
   agent-infra update          Update seed files and sync file registry for an existing project
   agent-infra version         Show version
 
@@ -100,6 +101,17 @@ switch (command) {
         });
         break;
     }
+    case 'task': {
+        const imported = await importCommand('../lib/task/index.ts');
+        if (!imported)
+            break;
+        const { runTask } = imported;
+        await runTask(process.argv.slice(3)).catch((e) => {
+            process.stderr.write(`Error: ${errorMessage(e)}\n`);
+            process.exit(1);
+        });
+        break;
+    }
     case 'cp': {
         const imported = await importCommand('../lib/cp.ts');
         if (!imported)

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/create.js

@@ -630,13 +630,21 @@ export function ensureCodexModelInheritance(toolDir, hostHomeDir) {
             return;
         }
     }
+    const inheritSpecs = [
+        ['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/dist/lib/sandbox/commands/enter.js

@@ -2,16 +2,17 @@ import { loadConfig } from "../config.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 { fetchSandboxRows, isTaskShortRef, resolveTaskShortRef } from "./list-running.js";
-const USAGE = `Usage: ai sandbox exec <branch | TASK-id | '#N'> [cmd...]
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, startSandboxContainer } from "./list-running.js";
+const USAGE = `Usage: ai sandbox exec <branch | TASK-id | N | '#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.`;
+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)
 // inspect to enable progressive enhancements such as the kitty keyboard
@@ -84,20 +85,18 @@ export async function enter(args) {
     validateClaudeCredentialsEnvOverride();
     const engine = detectEngine(config);
     const [firstArg = '', ...cmd] = args;
-    let branch;
-    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 {
             // 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}}';
 }
@@ -68,13 +69,14 @@ export function fetchSandboxRows(engine, label, branchKey) {
     return sortAndIndexSandboxRows(parseSandboxRows(raw, branchKey));
 }
 /**
- * Returns true iff `arg` is a syntactically valid task short reference ('#N').
+ * Returns true iff `arg` is a syntactically valid task short reference.
+ * Accepts both bare numeric ('11') and '#'-prefixed ('#11') forms.
  * 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) {
-    return /^#\d+$/.test(arg);
+    return /^#?\d+$/.test(arg);
 }
 /**
  * Try to resolve a short ref against the global task-short-id registry.
@@ -89,6 +91,9 @@ function tryResolveFromRegistry(arg, repoRoot) {
     const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
     if (!fs.existsSync(scriptPath))
         return { status: 'miss' };
+    // Strip leading '#' when forwarding bare-numeric input through the script's CLI.
+    // (Script accepts both forms, but this avoids shell quoting confusion in error
+    // messages echoed back to the user.)
     const result = spawnSync('node', [scriptPath, 'resolve', arg], { encoding: 'utf8', cwd: repoRoot });
     if (result.status !== 0)
         return { status: 'miss' };
@@ -113,41 +118,60 @@ function tryResolveFromRegistry(arg, repoRoot) {
     }
     throw new Error(`Short ref '${arg}' resolved to task ${taskId} but task.md was not found under any workspace dir`);
 }
-function resolveByRunningIndex(arg, running) {
-    const n = Number(arg.slice(1));
-    if (n < 1) {
-        throw new Error(`Invalid sandbox index '${arg}': must be >= 1`);
-    }
-    if (running.length === 0) {
-        throw new Error(`No running sandbox to reference with '${arg}'`);
-    }
-    if (n > running.length) {
-        throw new Error(`No running sandbox at index '${arg}' (only ${running.length} running)`);
-    }
-    const row = running[n - 1];
-    if (!row.branch) {
-        throw new Error(`Cannot resolve branch for sandbox '${arg}' (container '${row.name}' missing branch label)`);
-    }
-    return row.branch;
-}
 /**
- * Resolve a task short reference ('#N') to a branch name for the sandbox entrypoint.
+/**
+ * Resolve a task short reference (bare 'N' or '#N') to a branch name for the
+ * sandbox entrypoint.
  *
- * Resolution order (sandbox fallback mode, plan-r7 C2):
- *   1. Try the global task-short-id registry under repoRoot. If hit, look up the
- *      branch from the matching task.md.
- *   2. Fallback to the running-sandbox list index (preserves the #414 ls-index
- *      behaviour; long-term contract per analysis-r5).
+ * Resolution: registry-only. Look up the short id in the global task-short-id
+ * registry under repoRoot; if hit, read the branch from the matching task.md.
+ * On miss (registry empty or short id absent), throw with an actionable
+ * message instead of falling back to a container's row position in
+ * 'ai sandbox ls' output — that fallback would make the same syntax mean
+ * different things depending on `docker ps` state.
  *
  * Precondition: callers MUST gate on isTaskShortRef(arg) === true.
  */
 export function resolveTaskShortRef(arg, ctx) {
-    if (ctx.repoRoot) {
-        const lookup = tryResolveFromRegistry(arg, ctx.repoRoot);
-        if (lookup.status === 'hit')
-            return lookup.branch;
-        // 'miss' falls through to ls-index fallback (preserves #414 behaviour); 'hit-but-invalid' already threw above.
+    const lookup = tryResolveFromRegistry(arg, ctx.repoRoot);
+    if (lookup.status === 'hit')
+        return lookup.branch;
+    throw new Error(`short ref '${arg}' is not in the active task registry. ` +
+        `'#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'}`);
     }
-    return resolveByRunningIndex(arg, ctx.running);
 }
 //# sourceMappingURL=list-running.js.map

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

@@ -6,27 +6,22 @@ import { loadConfig } from "../config.js";
 import { sandboxBranchLabel, sandboxLabel } from "../constants.js";
 import { detectEngine } from "../engine.js";
 import { resolveTools, toolProjectDirCandidates } from "../tools.js";
+import { formatTable } from "../../table.js";
+import { lookupShortIdByBranch } from "../../task/short-id.js";
 import { fetchSandboxRows } from "./list-running.js";
 export { containerListFormat, parseLabels } from "./list-running.js";
 const USAGE = `Usage: ai sandbox ls
 
-Lists all containers for the current project. The leftmost '#' column
-numbers running sandboxes; use it as "ai sandbox exec '#N'" to enter one.
-Quote '#N' to avoid shell '#' comment handling.`;
-const CONTAINER_TABLE_HEADERS = ['#', 'NAMES', 'STATUS', 'BRANCH'];
-export function formatContainerTable(rows) {
-    const columns = rows.map((row) => [row.index, row.name, row.status, row.branch]);
-    const widths = [
-        Math.max(CONTAINER_TABLE_HEADERS[0].length, ...rows.map((row) => row.index.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.name.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.status.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[3].length, ...rows.map((row) => row.branch.length))
-    ];
-    const renderRow = (values) => `${values[0].padEnd(widths[0])}  ${values[1].padEnd(widths[1])}  ${values[2].padEnd(widths[2])}  ${values[3]}`.trimEnd();
-    return [
-        renderRow(CONTAINER_TABLE_HEADERS),
-        ...columns.map((column) => renderRow(column))
-    ];
+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').
+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, 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)) {
@@ -51,15 +46,23 @@ export function ls(args = []) {
         p.log.warn('  No sandbox containers');
     }
     else {
-        const tableRows = ordered.map((row) => ({
-            index: row.index === null ? '' : String(row.index),
-            name: row.name,
-            status: row.status,
-            branch: row.branch
-        }));
-        for (const line of formatContainerTable(tableRows)) {
+        const tableRows = ordered.map((container, i) => {
+            const shortId = container.branch ? lookupShortIdByBranch(container.branch, config.repoRoot) : null;
+            return {
+                row: String(i + 1),
+                shortId: shortId ?? '-',
+                name: container.name,
+                status: container.status,
+                branch: container.branch
+            };
+        });
+        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

@@ -2,9 +2,16 @@ const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
-  exec <branch | '#N'> [cmd...]
-                               Enter sandbox or run a command (use leftmost '#' column from 'ls')
-  ls                           List sandboxes for the current project
+  exec <branch | TASK-id | N | '#N'> [cmd...]
+                               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)
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
@@ -46,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/sandbox/task-resolver.js

@@ -2,7 +2,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
-const SHORT_ID_RE = /^#\d+$/;
+const SHORT_ID_RE = /^#?\d+$/;
 const WORKSPACE_DIRS = ['active', 'completed', 'blocked', 'archive'];
 function resolveShortIdStrict(arg, repoRoot) {
     const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');

package/dist/lib/sandbox/tools.js

@@ -6,7 +6,7 @@ function createBuiltinTools(home, project) {
         'claude-code': {
             id: 'claude-code',
             name: 'Claude Code',
-            install: { type: 'npm', cmd: '@anthropic-ai/claude-code@stable' },
+            install: { type: 'npm', cmd: '@anthropic-ai/claude-code@latest' },
             sandboxBase: hostJoin(home, '.agent-infra', 'sandboxes', 'claude-code'),
             containerMount: '/home/devuser/.claude',
             versionCmd: 'claude --version',

package/dist/lib/table.js

@@ -0,0 +1,38 @@
+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;
+        let max = headerLen;
+        for (const row of rows) {
+            const cell = row[i] ?? '';
+            if (cell.length > max)
+                max = cell.length;
+        }
+        return max;
+    });
+    const renderRow = (values) => {
+        const parts = [];
+        for (let i = 0; i < columnCount; i += 1) {
+            const cell = values[i] ?? '';
+            if (i === columnCount - 1) {
+                parts.push(cell);
+            }
+            else {
+                parts.push(cell.padEnd(widths[i]));
+            }
+        }
+        return parts.join('  ').trimEnd();
+    };
+    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