@fitlab-ai/agent-infra 0.6.5 → 0.7.0

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>From issue to merged PR in 9 commands.</strong> Define a requirement, let AI handle analysis, planning, coding, review, and delivery — you only step in when it matters.
+  <strong>From issue to merged PR in 11 commands.</strong> Define a requirement, let AI handle analysis, planning, coding, and three-stage review — you only step in when it matters.
 </p>
 
 <p align="center">
@@ -66,11 +66,23 @@ Once initialized, open the project in your AI TUI and install the latest skills:
 
 > AI scans the codebase, identifies `src/auth/login.ts` as the root cause, and writes `analysis.md`.
 
+```bash
+/review-analysis TASK-20260319-100000
+```
+
+> AI self-reviews the analysis: *"Approved. 0 blockers, 0 major, 0 minor — scope and root cause are clear, proceed to design."*
+
 ```bash
 /plan-task TASK-20260319-100000
 ```
 
 > AI proposes a fix plan: *"Sanitize the email input in `LoginService.validate()` and add a dedicated unit test."*
+
+```bash
+/review-plan TASK-20260319-100000
+```
+
+> AI self-reviews the plan: *"Approved with no findings. Ready for implementation."*
 >
 > **You review the plan and reply in natural language:**
 
@@ -79,22 +91,22 @@ The plan looks right, but don't change the DB schema.
 Just fix it at the application layer in LoginService.
 ```
 
-> AI updates the plan accordingly and confirms.
+> AI re-runs `/plan-task` to update the plan accordingly and confirms.
 
 ```bash
-/implement-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI writes the fix, adds a test case for `user+tag@example.com`, and runs all tests — green.
 
 ```bash
-/review-task TASK-20260319-100000
+/review-code TASK-20260319-100000
 ```
 
-> AI reviews its own implementation: *"Approved. 0 blockers, 0 major, 1 minor (missing JSDoc)."*
+> AI reviews its own code: *"Approved. 0 blockers, 0 major, 1 minor (missing JSDoc)."*
 
 ```bash
-/refine-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI fixes the minor issue and re-validates.
@@ -107,7 +119,7 @@ Just fix it at the application layer in LoginService.
 
 > Commit created, PR #43 opened (auto-linked to issue #42), task archived.
 
-**9 commands. 1 natural-language correction. From issue to merged PR.** That is the entire SOP — programming can have a standard operating procedure too.
+**11 commands. 1 natural-language correction. From issue to merged PR.** That is the entire SOP — programming can have a standard operating procedure too.
 
 Every command above works the same way in Claude Code, Codex, Gemini CLI, and OpenCode. Switch tools mid-task — the workflow state follows.
 
@@ -115,9 +127,9 @@ Every command above works the same way in Claude Code, Codex, Gemini CLI, and Op
 
 These are not thin command aliases. Each skill encapsulates standardized processes that are tedious and error-prone when done by hand:
 
-- **Structured artifacts** — every step produces a templated document (`analysis.md`, `plan.md`, `review.md`) with consistent structure, not free-form notes
+- **Structured artifacts** — every step produces a templated document (`analysis.md`, `review-analysis.md`, `plan.md`, `review-plan.md`, `code.md`, `review-code.md`) with consistent structure, not free-form notes
 - **Multi-round versioning** — requirements changed? Run `analyze-task` again to get `analysis-r2.md`; the full revision history is preserved
-- **Severity-classified reviews** — `review-task` categorizes findings into Blocker / Major / Minor with file paths and fix suggestions, not a vague "looks good"
+- **Severity-classified reviews** — `review-code` categorizes findings into Blocker / Major / Minor with file paths and fix suggestions, not a vague "looks good"
 - **Cross-tool state continuity** — `task.md` records who did what and when; Claude can analyze, Codex can implement, Gemini can review — context transfers seamlessly
 - **Audit trail and co-authorship** — every step appends to the Activity Log; the final commit includes `Co-Authored-By` lines for all participating AI agents
 
@@ -327,7 +339,7 @@ agent-infra is intentionally simple: a bootstrap CLI creates the seed configurat
 1. **Install** — `npm install -g @fitlab-ai/agent-infra` (or `brew install fitlab-ai/tap/agent-infra` on macOS, or use the shell script wrapper)
 2. **Initialize** — `ai init` in the project root to generate `.agents/.airc.json` and install the seed command
 3. **Render** — run `update-agent-infra` in any AI TUI to detect the bundled template version and generate all managed files
-4. **Develop** — use built-in skills to drive the full lifecycle: `analysis → design → implementation → review → fix → commit`
+4. **Develop** — use built-in skills to drive the full lifecycle: `analysis → analysis-review → design → design-review → code → code-review → commit`
 5. **Update** — run `update-agent-infra` again whenever a new template version is available
 
 ### Layered Architecture
@@ -524,10 +536,11 @@ agent-infra ships with **a rich set of built-in AI skills**. They are organized
 | `create-task` | Create a task scaffold from a natural-language request and cascade Issue creation through the platform rule when available. | `description` | Start a new feature, bug-fix, or improvement from scratch. |
 | `import-issue` | Import a GitHub Issue into the local task workspace. | `issue-number` | Convert an existing Issue into an actionable task folder. |
 | `analyze-task` | Produce a requirement analysis artifact for an existing task. | `task-id` | Capture scope, risks, and impacted files before designing. |
-| `plan-task` | Write the technical implementation plan with a review checkpoint. | `task-id` | Define the approach after analysis is complete. |
-| `implement-task` | Implement the approved plan and produce an implementation report. | `task-id` | Write code, tests, and docs after plan approval. |
-| `review-task` | Review the implementation and classify findings by severity. | `task-id` | Run a structured code review before merging. |
-| `refine-task` | Fix review findings in priority order without expanding scope. | `task-id` | Address review feedback and re-validate the task. |
+| `review-analysis` | Review the requirement analysis and classify findings by severity. | `task-id` | Confirm the analysis is complete before design. |
+| `plan-task` | Write the technical plan with a review checkpoint. | `task-id` | Define the approach after analysis approval. |
+| `review-plan` | Review the technical plan and classify findings by severity. | `task-id` | Confirm the design is actionable before coding. |
+| `code-task` | Implement the approved plan or fix code review findings, producing a code report. | `task-id` | Write code, tests, and docs after plan approval, or handle review feedback. |
+| `review-code` | Review the code and classify findings by severity. | `task-id` | Run a structured code review before merging. |
 | `complete-task` | Mark the task complete and archive it after all gates pass. | `task-id` | Close out a task after review, tests, and commit are done. |
 
 <a id="task-status"></a>
@@ -694,8 +707,8 @@ Supported `invoke` placeholders:
 
 | Placeholder | Replaced with | Example |
 |-------------|---------------|---------|
-| `${skillName}` | The skill command name, such as `review-task` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-task` |
-| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+| `${skillName}` | The skill command name, such as `review-code` or `commit`. | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
+| `${projectName}` | The `.airc.json` `project` value. Use this for namespaced commands. | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
 
 Non-namespaced custom TUI:
 
@@ -732,17 +745,17 @@ Namespaced custom TUI:
 
 ## Prebuilt Workflows
 
-agent-infra includes **4 prebuilt workflows**. Three of them share the same gated delivery lifecycle:
+agent-infra includes **4 prebuilt workflows**. Three of them share the same symmetric gated delivery lifecycle:
 
-`analysis -> design -> implementation -> review -> fix -> commit`
+`analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit`
 
 The fourth, `code-review`, is intentionally smaller and optimized for reviewing an existing PR or branch.
 
 | Workflow | Best for | Step chain |
 |----------|----------|------------|
-| `feature-development` | Building a new feature or capability | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `bug-fix` | Diagnosing and fixing a defect with regression coverage | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `refactoring` | Structural changes that should preserve behavior | `analysis -> design -> implementation -> review -> fix -> commit` |
+| `feature-development` | Building a new feature or capability | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `bug-fix` | Diagnosing and fixing a defect with regression coverage | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `refactoring` | Structural changes that should preserve behavior | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
 | `code-review` | Reviewing an existing PR or branch | `analysis -> review -> report` |
 
 ### Example lifecycle
@@ -758,20 +771,33 @@ import-issue #42                    Import task from GitHub Issue
   analyze-task T1                   Requirement analysis
          |
          v
-    plan-task T1                    Design solution  <-- human review
+  review-analysis T1                Review analysis
+         |
+     Issues?
+      +--YES----> analyze-task T1
+      |
+         v
+    plan-task T1                    Design solution
+         |
+         v
+  review-plan T1                    Review plan
+         |
+     Issues?
+      +--YES----> plan-task T1
+      |
          |
          v
-  implement-task T1                 Write code and tests
+  code-task T1                      Write code and tests
          |
          v
-  +-> review-task T1                Automated code review
+  +-> review-code T1                Automated code review
   |      |
   |   Issues?
   |      +--NO-------+
   |     YES          |
   |      |           |
   |      v           |
-  |  refine-task T1  |
+  |  code-task T1 (fix mode)
   |      |           |
   +------+           |
                      |

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>从 Issue 到合并 PR，只需 9 条命令。</strong> 定义需求，让 AI 完成分析、方案设计、编码、审查和交付 —— 你只需在关键节点介入。
+  <strong>从 Issue 到合并 PR，只需 11 条命令。</strong> 定义需求，让 AI 完成分析、方案设计、编码与三阶段审查 —— 你只需在关键节点介入。
 </p>
 
 <p align="center">
@@ -66,11 +66,23 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 > AI 扫描代码库，定位 `src/auth/login.ts` 为根因，输出 `analysis.md`。
 
+```bash
+/review-analysis TASK-20260319-100000
+```
+
+> AI 自审分析报告：*"通过。0 阻塞项，0 主要，0 次要 —— 范围与根因清晰，可进入方案设计。"*
+
 ```bash
 /plan-task TASK-20260319-100000
 ```
 
 > AI 提出修复方案：*"在 `LoginService.validate()` 中清洗邮箱输入，并添加专项单元测试。"*
+
+```bash
+/review-plan TASK-20260319-100000
+```
+
+> AI 自审方案：*"通过且无问题。可进入编码。"*
 >
 > **你审查方案后用自然语言回复：**
 
@@ -79,22 +91,22 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 只在应用层的 LoginService 里修复就行。
 ```
 
-> AI 按你的要求更新方案并确认。
+> AI 按你的要求重跑 `/plan-task` 更新方案并确认。
 
 ```bash
-/implement-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI 编写修复代码，添加 `user+tag@example.com` 的测试用例，运行全部测试 —— 通过。
 
 ```bash
-/review-task TASK-20260319-100000
+/review-code TASK-20260319-100000
 ```
 
 > AI 审查自己的实现：*"通过。0 阻塞项，0 主要问题，1 次要问题（缺少 JSDoc）。"*
 
 ```bash
-/refine-task TASK-20260319-100000
+/code-task TASK-20260319-100000
 ```
 
 > AI 修复次要问题并重新验证。
@@ -107,7 +119,7 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 > 提交完成，PR #43 已创建（自动关联 Issue #42），任务归档。
 
-**9 条命令，1 次自然语言纠正，从 Issue 到合并 PR。** 这就是完整的 SOP —— 编程也可以有标准作业流程。
+**11 条命令，1 次自然语言纠正，从 Issue 到合并 PR。** 这就是完整的 SOP —— 编程也可以有标准作业流程。
 
 以上每条命令在 Claude Code、Codex、Gemini CLI、OpenCode 中完全通用。任务进行到一半切换工具，工作流状态照常延续。
 
@@ -115,9 +127,9 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 这些不是简单的命令别名。每个 skill 都封装了手动操作时容易遗漏或不一致的标准化流程：
 
-- **结构化产物** — 每个步骤都输出模板化的文档（`analysis.md`、`plan.md`、`review.md`），格式统一，而非自由发挥的散文
+- **结构化产物** — 每个步骤都输出模板化的文档（`analysis.md`、`review-analysis.md`、`plan.md`、`review-plan.md`、`code.md`、`review-code.md`），格式统一，而非自由发挥的散文
 - **多轮版本化** — 需求变了？再执行一次 `analyze-task` 会生成 `analysis-r2.md`，完整修订历史自动保留
-- **分级审查机制** — `review-task` 按 Blocker / Major / Minor 分类问题，附带文件路径和修复建议，而非含糊的"看着没问题"
+- **分级审查机制** — `review-code` 按 Blocker / Major / Minor 分类问题，附带文件路径和修复建议，而非含糊的"看着没问题"
 - **跨工具状态延续** — `task.md` 记录了谁在什么时间做了什么；Claude 分析、Codex 实现、Gemini 审查——上下文无缝衔接
 - **审计轨迹与联合署名** — 每个步骤自动追加 Activity Log；最终提交包含所有参与 AI 的 `Co-Authored-By` 署名
 
@@ -300,7 +312,7 @@ agent-infra 的结构刻意保持简单：引导 CLI 负责生成种子配置，
 1. **安装** — `npm install -g @fitlab-ai/agent-infra`（或在 macOS 上使用 `brew install fitlab-ai/tap/agent-infra`，或使用 shell 脚本便捷封装）
 2. **初始化** — 在项目根目录运行 `ai init`，生成 `.agents/.airc.json` 并安装种子命令
 3. **渲染** — 在任意 AI TUI 中执行 `update-agent-infra`，检测当前打包模板版本并生成所有受管理文件
-4. **开发** — 使用内置 skill 驱动完整生命周期：`analysis → design → implementation → review → fix → commit`
+4. **开发** — 使用内置 skill 驱动完整生命周期：`analysis → analysis-review → design → design-review → code → code-review → commit`
 5. **升级** — 有新模板版本时再次执行 `update-agent-infra` 即可
 
 ### 分层架构
@@ -497,10 +509,11 @@ agent-infra 提供 **丰富的内置 AI skills**。它们按使用场景分组
 | `create-task` | 根据自然语言请求创建任务骨架，并在平台规则可用时级联创建 Issue。 | `description` | 从零开始记录新功能、缺陷或改进需求。 |
 | `import-issue` | 将 GitHub Issue 导入本地任务工作区。 | `issue-number` | 把已有 Issue 转成可执行的任务目录。 |
 | `analyze-task` | 为已有任务输出需求分析产物。 | `task-id` | 在设计前明确范围、风险和受影响文件。 |
-| `plan-task` | 编写技术实施方案，并设置人工审查检查点。 | `task-id` | 分析完成后定义具体实现路径。 |
-| `implement-task` | 按批准方案实施并生成实现报告。 | `task-id` | 在方案获批后编写代码、测试和文档。 |
-| `review-task` | 审查实现结果，并按严重程度分类问题。 | `task-id` | 合入前执行结构化代码审查。 |
-| `refine-task` | 按优先级修复审查问题，不额外扩张范围。 | `task-id` | 根据 review 反馈完成修正。 |
+| `review-analysis` | 审查需求分析产物，并按严重程度分类问题。 | `task-id` | 在设计前确认分析完整可用。 |
+| `plan-task` | 编写技术实施方案，并设置审查检查点。 | `task-id` | 分析获批后定义具体实现路径。 |
+| `review-plan` | 审查技术方案，并按严重程度分类问题。 | `task-id` | 在编码前确认方案可执行。 |
+| `code-task` | 按批准方案实施，或修复代码审查问题，并生成实现报告。 | `task-id` | 在方案获批后编写代码、测试和文档，或处理 review 反馈。 |
+| `review-code` | 审查实现结果，并按严重程度分类问题。 | `task-id` | 合入前执行结构化代码审查。 |
 | `complete-task` | 在所有关卡通过后标记任务完成并归档。 | `task-id` | 测试、审查和提交都完成后收尾。 |
 
 <a id="task-status"></a>
@@ -667,8 +680,8 @@ args: "<task-id>"   # 可选
 
 | 占位符 | 替换为 | 示例 |
 |--------|--------|------|
-| `${skillName}` | skill 命令名，例如 `review-task` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-task` |
-| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-task` |
+| `${skillName}` | skill 命令名，例如 `review-code` 或 `commit`。 | `<your-cli> ${skillName}` -> `<your-cli> review-code` |
+| `${projectName}` | `.airc.json` 中的 `project` 值，适用于带命名空间的命令。 | `/${projectName}:${skillName}` -> `/agent-infra:review-code` |
 
 不带命名空间的自定义 TUI：
 
@@ -707,15 +720,15 @@ args: "<task-id>"   # 可选
 
 agent-infra 内置 **4 个预置工作流**。其中 3 个共享同一条分阶段交付链路：
 
-`analysis -> design -> implementation -> review -> fix -> commit`
+`analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit`
 
 第 4 个 `code-review` 则更轻量，专门用于审查已有 PR 或分支。
 
 | Workflow | 适用场景 | 步骤链 |
 |----------|----------|--------|
-| `feature-development` | 开发新功能或新能力 | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `bug-fix` | 诊断并修复缺陷，同时补回归验证 | `analysis -> design -> implementation -> review -> fix -> commit` |
-| `refactoring` | 进行应保持行为稳定的结构性重构 | `analysis -> design -> implementation -> review -> fix -> commit` |
+| `feature-development` | 开发新功能或新能力 | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `bug-fix` | 诊断并修复缺陷，同时补回归验证 | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
+| `refactoring` | 进行应保持行为稳定的结构性重构 | `analysis -> analysis-review -> design -> design-review -> code -> code-review -> commit` |
 | `code-review` | 审查已有 Pull Request 或分支 | `analysis -> review -> report` |
 
 ### 生命周期示例
@@ -731,20 +744,33 @@ import-issue #42                    从 GitHub Issue 导入任务
   analyze-task T1                   需求分析
          |
          v
-    plan-task T1                    设计方案  <-- 人工审查
+  review-analysis T1                审查需求分析
+         |
+     有问题?
+      +--YES----> analyze-task T1
+      |
+         v
+    plan-task T1                    设计方案
+         |
+         v
+  review-plan T1                    审查技术方案
+         |
+     有问题?
+      +--YES----> plan-task T1
+      |
          |
          v
-  implement-task T1                 编写代码与测试
+  code-task T1                      编写代码与测试
          |
          v
-  +-> review-task T1                自动代码审查
+  +-> review-code T1                自动代码审查
   |      |
   |   有问题?
   |      +--NO-------+
   |     YES          |
   |      |           |
   |      v           |
-  |  refine-task T1  |
+  |  code-task T1 (fix mode)
   |      |           |
   +------+           |
                      |

package/dist/lib/defaults.json

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

package/dist/lib/init.js

@@ -156,6 +156,8 @@ 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';
     const templateSources = parseLocalSources(await prompt('Template sources (optional, comma-separated local paths, e.g. ~/my-templates; Enter to skip)', ''));
     const skillSources = parseLocalSources(await prompt('Skill sources (optional, comma-separated local paths, e.g. ~/my-skills; Enter to skip)', ''));
     closePrompt();
@@ -199,6 +201,7 @@ async function cmdInit() {
         org: orgName,
         language,
         platform: { type: platformType },
+        requiresPullRequest,
         templateVersion: VERSION,
         sandbox: structuredClone(defaults.sandbox),
         labels: structuredClone(defaults.labels),

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

@@ -13,7 +13,7 @@ import { prepareDockerfile } from "../dockerfile.js";
 import { detectEngine, ensureDocker } from "../engine.js";
 import { commandForEngine, execEngine, run, runEngine, runOk, runOkEngine, runSafe, runSafeEngine, runVerboseEngine } from "../shell.js";
 import { resolveTaskBranch } from "../task-resolver.js";
-import { resolveTools, toolConfigDirCandidates, toolNpmPackagesArg } from "../tools.js";
+import { imageSignatureFields, resolveTools, toolConfigDirCandidates, toolNpmPackagesArg, toolShellInstallScriptBase64 } from "../tools.js";
 import { hostJoin, toEnginePath, volumeArg } from "../engines/wsl2-paths.js";
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from "../clipboard/paths.js";
 import { validateSelinuxDisableEnv } from "../engines/selinux.js";
@@ -58,7 +58,7 @@ function buildSignature(preparedDockerfile, tools) {
     return createHash('sha256')
         .update(JSON.stringify({
         dockerfile: preparedDockerfile.signature,
-        tools: tools.map((tool) => tool.npmPackage)
+        tools: imageSignatureFields(tools)
     }))
         .digest('hex')
         .slice(0, 12);
@@ -789,6 +789,8 @@ export function buildImage(config, tools, dockerfilePath, imageSignature, { engi
         `HOST_GID=${hostGid}`,
         '--build-arg',
         `AI_TOOL_PACKAGES=${toolNpmPackagesArg(tools)}`,
+        '--build-arg',
+        `AI_TOOLS_SHELL_INSTALL_B64=${toolShellInstallScriptBase64(tools)}`,
         '--label',
         sandboxLabel(config),
         '--label',

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

@@ -1,5 +1,5 @@
 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";
@@ -7,7 +7,11 @@ import { resolveTaskBranch } from "../task-resolver.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
 import { runInteractiveWithClipboardBridge } from "../clipboard/bridge.js";
 import { detectHostTimezone } from "../host-timezone.js";
-const USAGE = `Usage: ai sandbox exec <branch> [cmd...]`;
+import { fetchSandboxRows, isTaskShortRef, resolveTaskShortRef } from "./list-running.js";
+const USAGE = `Usage: ai sandbox exec <branch | TASK-id | '#N'> [cmd...]
+
+'#N' references the N-th running sandbox in 'ai sandbox ls' order (1-based).
+Quote it as '#N' to avoid shell '#' comment handling.`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
 // inspect to enable progressive enhancements such as the kitty keyboard
@@ -79,8 +83,15 @@ export async function enter(args) {
     const config = loadConfig();
     validateClaudeCredentialsEnvOverride();
     const engine = detectEngine(config);
-    const [branchOrTaskId = '', ...cmd] = args;
-    const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
+    const [firstArg = '', ...cmd] = args;
+    let branch;
+    if (isTaskShortRef(firstArg)) {
+        const { running } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+        branch = resolveTaskShortRef(firstArg, { running });
+    }
+    else {
+        branch = resolveTaskBranch(firstArg, config.repoRoot);
+    }
     assertValidBranchName(branch);
     const running = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
     const container = containerNameCandidates(config, branch).find((name) => running.includes(name));

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

@@ -0,0 +1,108 @@
+import { runSafeEngine } from "../shell.js";
+export function containerListFormat() {
+    return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
+}
+export function parseLabels(csv) {
+    if (!csv) {
+        return {};
+    }
+    const labels = {};
+    for (const pair of csv.split(',')) {
+        if (!pair) {
+            continue;
+        }
+        const eq = pair.indexOf('=');
+        if (eq < 0) {
+            continue;
+        }
+        labels[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return labels;
+}
+export function parseSandboxRows(rawOutput, branchKey) {
+    if (!rawOutput) {
+        return [];
+    }
+    return rawOutput.split('\n').map((line) => {
+        const [name = '', status = '', labelsCsv = ''] = line.split('\t');
+        const branch = parseLabels(labelsCsv)[branchKey] ?? '';
+        return {
+            name,
+            status,
+            branch,
+            running: status.startsWith('Up '),
+            index: null
+        };
+    });
+}
+export function sortAndIndexSandboxRows(rows) {
+    const byName = (a, b) => {
+        if (a.name < b.name)
+            return -1;
+        if (a.name > b.name)
+            return 1;
+        return 0;
+    };
+    const running = rows.filter((row) => row.running).sort(byName).map((row, i) => ({
+        ...row,
+        index: i + 1
+    }));
+    const nonRunning = rows.filter((row) => !row.running).sort(byName).map((row) => ({
+        ...row,
+        index: null
+    }));
+    return { running, nonRunning };
+}
+export function fetchSandboxRows(engine, label, branchKey) {
+    const raw = runSafeEngine(engine, 'docker', [
+        'ps',
+        '-a',
+        '--filter',
+        `label=${label}`,
+        '--format',
+        containerListFormat()
+    ]);
+    return sortAndIndexSandboxRows(parseSandboxRows(raw, branchKey));
+}
+/**
+ * Returns true iff `arg` is a syntactically valid task short reference ('#N').
+ * Zero IO. Callers MUST use this as the gate before constructing any context
+ * for resolveTaskShortRef — that way non-matching arguments (e.g. '#abc',
+ * '#1.5', '#') never trigger sandbox list IO.
+ */
+export function isTaskShortRef(arg) {
+    return /^#\d+$/.test(arg);
+}
+/**
+ * Resolve a task short reference ('#N') to a branch name.
+ *
+ * Current implementation: treats the digits as a 1-based index into the
+ * supplied running-sandbox list (ls view order). This is the *only*
+ * resolution path until the global task-short-id registry lands in a
+ * follow-up task; do NOT read task.md or scan .agents/workspace/ from this
+ * helper here.
+ *
+ * Precondition: callers MUST gate on isTaskShortRef(arg) === true before
+ * constructing ctx and calling this function. Throws when arg is a valid
+ * short ref but cannot be resolved (out of range, no running sandboxes,
+ * etc.); the caller surfaces the error to the user.
+ */
+export function resolveTaskShortRef(arg, ctx) {
+    const n = Number(arg.slice(1));
+    if (n < 1) {
+        throw new Error(`Invalid sandbox index '${arg}': must be >= 1`);
+    }
+    const { running } = ctx;
+    if (running.length === 0) {
+        throw new Error(`No running sandbox to reference with '${arg}'`);
+    }
+    if (n > running.length) {
+        throw new Error(`No running sandbox at index '${arg}' (only ${running.length} running)`);
+    }
+    const row = running[n - 1];
+    if (!row.branch) {
+        throw new Error(`Cannot resolve branch for sandbox '${arg}' (container '${row.name}' missing branch label)`);
+    }
+    return row.branch;
+}
+//# sourceMappingURL=list-running.js.map

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

@@ -5,39 +5,24 @@ import pc from 'picocolors';
 import { loadConfig } from "../config.js";
 import { sandboxBranchLabel, sandboxLabel } from "../constants.js";
 import { detectEngine } from "../engine.js";
-import { runSafeEngine } from "../shell.js";
 import { resolveTools, toolProjectDirCandidates } from "../tools.js";
-const USAGE = 'Usage: ai sandbox ls';
-const CONTAINER_TABLE_HEADERS = ['NAMES', 'STATUS', 'BRANCH'];
-// Exported to lock the docker/podman-compatible format in unit tests.
-export function containerListFormat() {
-    return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
-}
-export function parseLabels(csv) {
-    if (!csv) {
-        return {};
-    }
-    const labels = {};
-    for (const pair of csv.split(',')) {
-        if (!pair) {
-            continue;
-        }
-        const eq = pair.indexOf('=');
-        if (eq < 0) {
-            continue;
-        }
-        labels[pair.slice(0, eq)] = pair.slice(eq + 1);
-    }
-    return labels;
-}
+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.name, row.status, row.branch]);
+    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.name.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[1].length, ...rows.map((row) => row.status.length)),
-        Math.max(CONTAINER_TABLE_HEADERS[2].length, ...rows.map((row) => row.branch.length))
+        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]}`.trimEnd();
+    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))
@@ -58,27 +43,21 @@ export function ls(args = []) {
     const engine = detectEngine(config);
     const tools = resolveTools(config);
     const label = sandboxLabel(config);
-    const containers = runSafeEngine(engine, 'docker', [
-        'ps',
-        '-a',
-        '--filter',
-        `label=${label}`,
-        '--format',
-        containerListFormat()
-    ]);
+    const { running, nonRunning } = fetchSandboxRows(engine, label, sandboxBranchLabel(config));
     p.intro(pc.cyan(`Sandbox status for ${config.project}`));
     p.log.step('Containers');
-    if (!containers) {
+    const ordered = [...running, ...nonRunning];
+    if (ordered.length === 0) {
         p.log.warn('  No sandbox containers');
     }
     else {
-        const branchKey = sandboxBranchLabel(config);
-        const rows = containers.split('\n').map((line) => {
-            const [name = '', status = '', labelsCsv = ''] = line.split('\t');
-            const branch = parseLabels(labelsCsv)[branchKey] ?? '';
-            return { name, status, branch };
-        });
-        for (const line of formatContainerTable(rows)) {
+        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)) {
             process.stdout.write(`  ${line}\n`);
         }
     }