@fitlab-ai/agent-infra 0.7.2 → 0.7.4

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');

package/lib/sandbox/commands/rm.ts

@@ -21,15 +21,27 @@ import { runOk, runSafe, runSafeEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
+import { fetchSandboxRows } from './list-running.ts';
+import { lookupShortIdByBranch } from '../../task/short-id.ts';
 
-const USAGE = `Usage: ai sandbox rm <branch> [--all]`;
+const USAGE = `Usage:
+  ai sandbox rm <branch>                    Remove one sandbox (branch | TASK-id | short id)
+  ai sandbox rm --all [--dry-run] [--yes]   Remove every sandbox not bound to an active task
+  ai sandbox rm --purge                     Tear down ALL sandboxes for the project (containers, worktrees, image, VM)`;
 export { assertManagedPath } from '../managed-fs.ts';
 
 function projectToolDirs(config: SandboxConfig, tools: SandboxTool[]): string[] {
   return tools.flatMap((tool) => toolProjectDirCandidates(tool, config.project));
 }
 
-async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string): Promise<void> {
+type RmOneOptions = { assumeYes?: boolean; quiet?: boolean };
+
+async function rmOne(
+  config: SandboxConfig,
+  tools: SandboxTool[],
+  branch: string,
+  options: RmOneOptions = {}
+): Promise<void> {
   assertValidBranchName(branch);
   const engine = detectEngine(config);
   let effectiveBranch = branch;
@@ -39,7 +51,9 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
     candidates: toolConfigDirCandidates(tool, config.project, branch)
   }));
 
-  p.intro(pc.cyan(`Removing sandbox for ${branch}`));
+  if (!options.quiet) {
+    p.intro(pc.cyan(`Removing sandbox for ${branch}`));
+  }
 
   const existing = runSafeEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
   const matchedContainers = containerNameCandidates(config, branch)
@@ -74,10 +88,12 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
 
   const existingWorktrees = worktreeCandidates.filter((candidate) => fs.existsSync(candidate));
   if (existingWorktrees.length > 0) {
-    const shouldRemoveWorktree = await p.confirm({
-      message: `Remove worktree(s): ${existingWorktrees.join(', ')}?`,
-      initialValue: true
-    });
+    const shouldRemoveWorktree = options.assumeYes
+      ? true
+      : await p.confirm({
+          message: `Remove worktree(s): ${existingWorktrees.join(', ')}?`,
+          initialValue: true
+        });
 
     if (p.isCancel(shouldRemoveWorktree)) {
       p.outro('Cancelled');
@@ -89,10 +105,12 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
         removeWorktreeDir(config.repoRoot, config.worktreeBase, worktree);
       }
 
-      const shouldDeleteBranch = await p.confirm({
-        message: `Also delete local branch '${effectiveBranch}'?`,
-        initialValue: true
-      });
+      const shouldDeleteBranch = options.assumeYes
+        ? true
+        : await p.confirm({
+            message: `Also delete local branch '${effectiveBranch}'?`,
+            initialValue: true
+          });
 
       if (!p.isCancel(shouldDeleteBranch) && shouldDeleteBranch) {
         if (!runOk('git', ['-C', config.repoRoot, 'branch', '-D', effectiveBranch])) {
@@ -116,20 +134,24 @@ async function rmOne(config: SandboxConfig, tools: SandboxTool[], branch: string
 
   const shareBranch = shareBranchDir(config, effectiveBranch);
   if (fs.existsSync(shareBranch)) {
-    const shouldRemoveShare = await p.confirm({
-      message: `Remove share dir for branch '${effectiveBranch}' (${shareBranch})?`,
-      initialValue: true
-    });
+    const shouldRemoveShare = options.assumeYes
+      ? true
+      : await p.confirm({
+          message: `Remove share dir for branch '${effectiveBranch}' (${shareBranch})?`,
+          initialValue: true
+        });
     if (!p.isCancel(shouldRemoveShare) && shouldRemoveShare) {
       removeManagedDir(config.shareBase, shareBranch);
       p.log.success(`Share dir removed: ${shareBranch}`);
     }
   }
 
-  p.outro(pc.green('Sandbox removed'));
+  if (!options.quiet) {
+    p.outro(pc.green('Sandbox removed'));
+  }
 }
 
-async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void> {
+async function rmPurge(config: SandboxConfig, tools: SandboxTool[]): Promise<void> {
   const engine = detectEngine(config);
   p.intro(pc.cyan(`Removing all sandboxes for ${config.project}`));
 
@@ -231,6 +253,70 @@ async function rmAll(config: SandboxConfig, tools: SandboxTool[]): Promise<void>
   p.outro(pc.green('All project sandboxes removed'));
 }
 
+async function rmUnbound(
+  config: SandboxConfig,
+  tools: SandboxTool[],
+  options: { dryRun: boolean; assumeYes: boolean }
+): Promise<void> {
+  const engine = detectEngine(config);
+  const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+  const removable = [...running, ...nonRunning].filter(
+    (row) => row.branch && lookupShortIdByBranch(row.branch, config.repoRoot) === null
+  );
+
+  p.intro(pc.cyan(`Removing sandboxes not bound to an active task for ${config.project}`));
+
+  if (removable.length === 0) {
+    p.outro('No removable sandboxes: every container is bound to an active task (or none exist)');
+    return;
+  }
+
+  for (const row of removable) {
+    p.log.message(`${row.name}  ${row.branch}`);
+  }
+
+  if (options.dryRun) {
+    p.outro(`Dry run: ${removable.length} sandbox(es) would be removed, nothing deleted`);
+    return;
+  }
+
+  if (!options.assumeYes) {
+    if (!process.stdin.isTTY) {
+      throw new Error(
+        'Refusing to remove sandboxes without confirmation in a non-interactive shell; pass --yes to proceed.'
+      );
+    }
+    const confirmed = await p.confirm({
+      message: `Remove these ${removable.length} sandbox(es)?`,
+      initialValue: false
+    });
+    if (p.isCancel(confirmed) || !confirmed) {
+      p.outro('Cancelled');
+      return;
+    }
+  }
+
+  const failures: { branch: string; message: string }[] = [];
+  for (const row of removable) {
+    try {
+      await rmOne(config, tools, row.branch, { assumeYes: true, quiet: true });
+    } catch (error) {
+      failures.push({ branch: row.branch, message: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
+  if (failures.length > 0) {
+    for (const failure of failures) {
+      p.log.error(`Failed to remove '${failure.branch}': ${failure.message}`);
+    }
+    throw new Error(
+      `Removed ${removable.length - failures.length}/${removable.length} sandbox(es); ${failures.length} failed`
+    );
+  }
+
+  p.outro(pc.green(`Removed ${removable.length} sandbox(es)`));
+}
+
 export async function rm(args: string[]): Promise<void> {
   const { values, positionals } = parseArgs({
     args,
@@ -238,6 +324,9 @@ export async function rm(args: string[]): Promise<void> {
     strict: true,
     options: {
       all: { type: 'boolean' },
+      purge: { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      yes: { type: 'boolean', short: 'y' },
       help: { type: 'boolean', short: 'h' }
     }
   });
@@ -247,15 +336,35 @@ export async function rm(args: string[]): Promise<void> {
     return;
   }
 
-  if (!values.all && positionals.length !== 1) {
+  if (values.all && values.purge) {
+    throw new Error('--all and --purge are mutually exclusive');
+  }
+
+  if ((values['dry-run'] || values.yes) && !values.all) {
+    throw new Error('--dry-run and --yes only apply to --all');
+  }
+
+  if ((values.all || values.purge) && positionals.length > 0) {
+    throw new Error(`${values.all ? '--all' : '--purge'} does not take a branch argument`);
+  }
+
+  if (!values.all && !values.purge && positionals.length !== 1) {
     throw new Error(USAGE);
   }
 
   const config = loadConfig();
   const tools = resolveTools(config);
 
+  if (values.purge) {
+    await rmPurge(config, tools);
+    return;
+  }
+
   if (values.all) {
-    await rmAll(config, tools);
+    await rmUnbound(config, tools, {
+      dryRun: Boolean(values['dry-run']),
+      assumeYes: Boolean(values.yes)
+    });
     return;
   }
 

package/lib/sandbox/commands/start.ts

@@ -0,0 +1,61 @@
+import { loadConfig } from '../config.ts';
+import {
+  assertValidBranchName,
+  containerNameCandidates,
+  sandboxBranchLabel,
+  sandboxLabel
+} from '../constants.ts';
+import { detectEngine } from '../engine.ts';
+import {
+  fetchSandboxRows,
+  resolveBranchArg,
+  selectSandboxContainer,
+  startSandboxContainer
+} from './list-running.ts';
+
+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: string[]): Promise<void> {
+  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`);
+}

package/lib/sandbox/index.ts

@@ -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)
@@ -13,7 +16,9 @@ Commands:
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
   refresh                      Sync host Claude Code credentials to all sandbox copies
-  rm <branch> [--all]          Remove a sandbox or all sandboxes
+  rm <branch> | --all | --purge
+                               Remove one sandbox, all sandboxes not bound to an
+                               active task (--all), or tear down everything (--purge)
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;
@@ -54,6 +59,11 @@ export async function runSandbox(args: string[]): Promise<void> {
       }
       break;
     }
+    case 'start': {
+      const { start } = await import('./commands/start.ts');
+      await start(rest);
+      break;
+    }
     case 'ls': {
       const { ls } = await import('./commands/ls.ts');
       ls(rest);

package/lib/sandbox/readme-scaffold.ts

@@ -18,7 +18,7 @@ symlink under \`$HOME\` (e.g. \`.tmux.conf\` -> \`/home/devuser/.tmux.conf\`),
 overriding image defaults so your editor, shell, and tool preferences follow
 you across \`ai sandbox destroy + create\`.
 
-See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#user-level-dotfiles-channel
+See: https://github.com/fitlab-ai/agent-infra/blob/main/docs/en/sandbox.md#user-level-dotfiles-channel
 
 Common usage - drop files or symlinks here:
 
@@ -46,7 +46,7 @@ only writes \`README.md\` when it is missing, never when it already exists.
 （例如 \`.tmux.conf -> /home/devuser/.tmux.conf\`），覆盖镜像默认值，让你的编辑器、
 shell、工具偏好跨 \`ai sandbox destroy + create\` 持久存在。
 
-参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#用户级-dotfiles-通道
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/docs/zh-CN/sandbox.md#用户级-dotfiles-通道
 
 常见用法：把文件或符号链接放进来：
 
@@ -72,7 +72,7 @@ This directory is mounted **read-write** into every sandbox container of this
 project at \`/share/common\`, regardless of branch. Drop files here to share
 between host and any sandbox without polluting the git worktree.
 
-See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+See: https://github.com/fitlab-ai/agent-infra/blob/main/docs/en/sandbox.md#host-sandbox-file-exchange
 
 This file is safe to delete; the next \`ai sandbox create\` will re-create it.
 
@@ -83,7 +83,7 @@ This file is safe to delete; the next \`ai sandbox create\` will re-create it.
 该目录被以**读写**方式挂载到本项目所有 sandbox 容器的 \`/share/common\`，
 跨分支可见。可用来在宿主和任意 sandbox 之间传文件，无需弄脏 git worktree。
 
-参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/docs/zh-CN/sandbox.md#宿主-沙箱文件交换
 
 该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
 `;
@@ -94,7 +94,7 @@ This directory is mounted **read-write** into the sandbox container of this
 project's current branch at \`/share/branch\`. Files here are exclusive to this
 branch's sandbox and do not leak across branches.
 
-See: https://github.com/fitlab-ai/agent-infra/blob/main/README.md#host-sandbox-file-exchange
+See: https://github.com/fitlab-ai/agent-infra/blob/main/docs/en/sandbox.md#host-sandbox-file-exchange
 
 This file is safe to delete; the next \`ai sandbox create\` will re-create it.
 
@@ -105,7 +105,7 @@ This file is safe to delete; the next \`ai sandbox create\` will re-create it.
 该目录被以**读写**方式挂载到本项目当前分支 sandbox 容器的 \`/share/branch\`，
 仅当前分支可见，不会跨分支泄漏。
 
-参考：https://github.com/fitlab-ai/agent-infra/blob/main/README.zh-CN.md#宿主-沙箱文件交换
+参考：https://github.com/fitlab-ai/agent-infra/blob/main/docs/zh-CN/sandbox.md#宿主-沙箱文件交换
 
 该文件可以安全删除；下一次 \`ai sandbox create\` 会重新生成。
 `;

package/lib/table.ts

@@ -1,7 +1,11 @@
+import pc from 'picocolors';
+
 function formatTable(
   headers: readonly string[],
-  rows: readonly (readonly string[])[]
+  rows: readonly (readonly string[])[],
+  options: { zebra?: boolean } = {}
 ): string[] {
+  const { zebra = false } = options;
   const columnCount = headers.length;
   const widths = headers.map((header, i) => {
     const headerLen = header.length;
@@ -26,7 +30,15 @@ function formatTable(
     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 };

package/lib/task/artifacts.ts

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+type Artifact = {
+  index: number;
+  name: string;
+  path: string;
+  size: number;
+  mtimeMs: number;
+};
+
+/**
+ * Enumerate a task directory's artifacts ordered by modification time, oldest
+ * first, so the listing reads like the task's timeline. Filename ascending is a
+ * deterministic tiebreak when two files share the same mtime (e.g. written in
+ * the same millisecond).
+ *
+ * Only top-level regular files are included; subdirectories and dotfiles are
+ * skipped so every entry is something `cat` can print. The returned 1-based
+ * `index` is the source of truth shared by `files` and `cat`.
+ */
+function enumerateArtifacts(taskDir: string): Artifact[] {
+  const entries = fs
+    .readdirSync(taskDir, { withFileTypes: true })
+    .filter((dirent) => dirent.isFile() && !dirent.name.startsWith('.'))
+    .map((dirent) => {
+      const abs = path.join(taskDir, dirent.name);
+      const stat = fs.statSync(abs);
+      return { name: dirent.name, path: abs, size: stat.size, mtimeMs: stat.mtimeMs };
+    });
+
+  entries.sort((a, b) => {
+    if (a.mtimeMs !== b.mtimeMs) return a.mtimeMs - b.mtimeMs;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+  });
+
+  return entries.map((entry, i) => ({ index: i + 1, ...entry }));
+}
+
+/**
+ * Resolve an artifact selector to an absolute path within `taskDir`. The
+ * selector is either a 1-based index `N` (as listed by `files`) or a filename
+ * (with or without the `.md` suffix). Throws with a clear message on failure.
+ */
+function resolveArtifact(taskDir: string, artifactOrN: string): string {
+  if (path.basename(artifactOrN) !== artifactOrN) {
+    throw new Error('artifact name must not contain path separators');
+  }
+
+  if (/^\d+$/.test(artifactOrN)) {
+    const n = Number(artifactOrN);
+    const match = enumerateArtifacts(taskDir).find((a) => a.index === n);
+    if (!match) {
+      throw new Error(`invalid artifact index ${n} (run 'ai task files <ref>' to list)`);
+    }
+    return match.path;
+  }
+
+  const candidates = artifactOrN.endsWith('.md')
+    ? [artifactOrN]
+    : [artifactOrN, `${artifactOrN}.md`];
+  for (const candidate of candidates) {
+    const abs = path.join(taskDir, candidate);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      return abs;
+    }
+  }
+  throw new Error(`artifact '${artifactOrN}' not found in task directory`);
+}
+
+export { enumerateArtifacts, resolveArtifact };
+export type { Artifact };

package/lib/task/commands/cat.ts

@@ -0,0 +1,39 @@
+import fs from 'node:fs';
+import { resolveTaskRef } from '../resolve-ref.ts';
+import { resolveArtifact } from '../artifacts.ts';
+
+const USAGE = `Usage: ai task cat <N | #N | TASK-id> <artifact | N>
+
+Prints a task artifact's raw content to stdout.
+  <ref>            Bare numeric / '#N' short id, or a full TASK-YYYYMMDD-HHMMSS id.
+  <artifact | N>   Artifact filename (with or without '.md'), or the number from 'ai task files'.
+`;
+
+function cat(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  if (args.length < 2) {
+    process.stdout.write(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  const resolved = resolveTaskRef(args[0]!);
+  if (!resolved.ok) {
+    process.stderr.write(`ai task cat: ${resolved.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  let artifactPath: string;
+  try {
+    artifactPath = resolveArtifact(resolved.taskDir, args[1]!);
+  } catch (e) {
+    process.stderr.write(`ai task cat: ${(e as Error).message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(fs.readFileSync(artifactPath, 'utf8'));
+}
+
+export { cat };