@fitlab-ai/agent-infra 0.7.1 → 0.7.3

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;
@@ -88,13 +89,14 @@ export function fetchSandboxRows(
 }
 
 /**
- * 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: string): boolean {
-  return /^#\d+$/.test(arg);
+  return /^#?\d+$/.test(arg);
 }
 
 type RegistryLookup =
@@ -113,6 +115,9 @@ type RegistryLookup =
 function tryResolveFromRegistry(arg: string, repoRoot: string): RegistryLookup {
   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' };
   const taskId = (result.stdout || '').trim();
@@ -142,47 +147,70 @@ function tryResolveFromRegistry(arg: string, repoRoot: string): RegistryLookup {
   );
 }
 
-function resolveByRunningIndex(arg: string, running: SandboxRow[]): string {
-  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: string,
-  ctx: { running: SandboxRow[]; repoRoot?: string }
+  ctx: { repoRoot: string }
 ): string {
-  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: 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'}`
+    );
   }
-  return resolveByRunningIndex(arg, ctx.running);
 }

package/lib/sandbox/commands/ls.ts

@@ -6,40 +6,38 @@ import { loadConfig } from '../config.ts';
 import { sandboxBranchLabel, sandboxLabel } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import { resolveTools, toolProjectDirCandidates } from '../tools.ts';
+import { formatTable } from '../../table.ts';
+import { lookupShortIdByBranch } from '../../task/short-id.ts';
 import { fetchSandboxRows } from './list-running.ts';
 
 export { containerListFormat, parseLabels } from './list-running.ts';
 
 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.`;
+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 = ['#', 'NAMES', 'STATUS', 'BRANCH'] as const;
+const CONTAINER_TABLE_HEADERS = ['#', 'SHORT', 'NAMES', 'STATUS', 'BRANCH'] as const;
 
 type ContainerTableRow = {
-  index: string;
+  row: string;
+  shortId: string;
   name: string;
   status: string;
   branch: string;
 };
 
-export function formatContainerTable(rows: ContainerTableRow[]): string[] {
-  const columns = rows.map((row) => [row.index, row.name, row.status, row.branch] as const);
-  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))
-  ] as const;
-  const renderRow = (values: readonly [string, string, string, string]): string =>
-    `${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))
-  ];
+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]),
+    { zebra }
+  );
 }
 
 function listChildren(dir: string): string[] {
@@ -69,15 +67,25 @@ export function ls(args: string[] = []): void {
   if (ordered.length === 0) {
     p.log.warn('  No sandbox containers');
   } else {
-    const tableRows: ContainerTableRow[] = 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: ContainerTableRow[] = 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');

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

@@ -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)
@@ -50,6 +57,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/task-resolver.ts

@@ -3,7 +3,7 @@ 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: string, repoRoot: string): string {

package/lib/sandbox/tools.ts

@@ -35,7 +35,7 @@ function createBuiltinTools(home: string, project: string): Record<string, Sandb
     '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/lib/table.ts

@@ -0,0 +1,44 @@
+import pc from 'picocolors';
+
+function formatTable(
+  headers: 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;
+    let max = headerLen;
+    for (const row of rows) {
+      const cell = row[i] ?? '';
+      if (cell.length > max) max = cell.length;
+    }
+    return max;
+  });
+
+  const renderRow = (values: readonly string[]): string => {
+    const parts: string[] = [];
+    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 };

package/lib/task/commands/ls.ts

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { formatTable } from '../../table.ts';
+import { parseTaskFrontmatter, extractTitle } from '../frontmatter.ts';
+import { loadShortIdByTaskId } from '../short-id.ts';
+
+const USAGE = `Usage: ai task ls [--all | --blocked | --completed]
+
+Lists tasks under .agents/workspace/. Defaults to active tasks only.
+  --all         Include active + blocked + completed (excludes archive)
+  --blocked     Only blocked tasks
+  --completed   Only completed tasks
+
+Columns: # (display-only row number) / SHORT (task short id, usable as an argument) / type / status / current_step / branch / title
+`;
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+const TABLE_HEADERS = ['#', 'SHORT', 'TYPE', 'STATUS', 'STEP', 'BRANCH', 'TITLE'] as const;
+
+type Selection = ('active' | 'blocked' | 'completed')[];
+
+function detectRepoRoot(): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    throw new Error('ai task: current directory is not inside a git repository');
+  }
+}
+
+type ParseResult =
+  | { ok: true; selection: Selection }
+  | { ok: false; message: string };
+
+function parseSelection(args: string[]): ParseResult {
+  const positional = args.filter((a) => !a.startsWith('--'));
+  if (positional.length > 0) {
+    return {
+      ok: false,
+      message: `ai task ls: unexpected positional argument(s): ${positional.join(' ')}`
+    };
+  }
+  const flags = args.filter((a) => a.startsWith('--'));
+  if (flags.length === 0) return { ok: true, selection: ['active'] };
+  if (flags.length > 1) {
+    return {
+      ok: false,
+      message: 'ai task ls: pass at most one of --all / --blocked / --completed'
+    };
+  }
+  switch (flags[0]) {
+    case '--all':
+      return { ok: true, selection: ['active', 'blocked', 'completed'] };
+    case '--blocked':
+      return { ok: true, selection: ['blocked'] };
+    case '--completed':
+      return { ok: true, selection: ['completed'] };
+    default:
+      return { ok: false, message: `ai task ls: unknown flag: ${flags[0]}` };
+  }
+}
+
+type TaskRow = {
+  shortId: string;
+  type: string;
+  status: string;
+  step: string;
+  branch: string;
+  title: string;
+};
+
+function collectTasks(repoRoot: string, state: 'active' | 'blocked' | 'completed'): TaskRow[] {
+  const dir = path.join(repoRoot, '.agents', 'workspace', state);
+  if (!fs.existsSync(dir)) return [];
+  // Short ids live only in the registry and only for active tasks; archived
+  // (blocked/completed) tasks have released their short id and render '-'.
+  const shortIdByTaskId = state === 'active' ? loadShortIdByTaskId(repoRoot) : new Map<string, string>();
+  const rows: TaskRow[] = [];
+  for (const entry of fs.readdirSync(dir).sort()) {
+    if (!TASK_ID_RE.test(entry)) continue;
+    const taskMdPath = path.join(dir, entry, 'task.md');
+    if (!fs.existsSync(taskMdPath)) continue;
+    const content = fs.readFileSync(taskMdPath, 'utf8');
+    const fm = parseTaskFrontmatter(content);
+    const title = extractTitle(content);
+    const shortId = shortIdByTaskId.get(entry) ?? '-';
+    rows.push({
+      shortId,
+      type: fm.type ?? '-',
+      status: fm.status ?? state,
+      step: fm.current_step ?? '-',
+      branch: fm.branch ?? '-',
+      title: title || fm.id || entry
+    });
+  }
+  return rows;
+}
+
+function ls(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return;
+  }
+  const result = parseSelection(args);
+  if (!result.ok) {
+    process.stderr.write(`${result.message}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  const { selection } = result;
+  const repoRoot = detectRepoRoot();
+  const rows: TaskRow[] = [];
+  for (const state of selection) {
+    rows.push(...collectTasks(repoRoot, state));
+  }
+  if (rows.length === 0) {
+    process.stdout.write(`No tasks under .agents/workspace/${selection.join('|')}\n`);
+    return;
+  }
+  const tableRows = rows.map((r, i) => [
+    String(i + 1),
+    r.shortId,
+    r.type,
+    r.status,
+    r.step,
+    r.branch,
+    r.title
+  ]);
+  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`);
+}
+
+export { ls };

package/lib/task/commands/show.ts

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { normalizeShortIdInput } from '../short-id.ts';
+
+const USAGE = `Usage: ai task show <N | #N | TASK-id>
+
+Prints the task.md content for the matching task.
+  N (bare numeric)   Recommended; resolves the active short id via the registry.
+  '#N'               Compatibility form for old commands.
+  TASK-YYYYMMDD-HHMMSS  Locates a task in active / blocked / completed / archive.
+`;
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+// Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
+// Note: `archive` uses a three-level YYYY/MM/DD layout and is handled separately.
+const FLAT_WORKSPACE_DIRS = ['active', 'blocked', 'completed'] as const;
+
+function detectRepoRoot(): string {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    }).trim();
+  } catch {
+    throw new Error('ai task: current directory is not inside a git repository');
+  }
+}
+
+function readShortIdLength(repoRoot: string): number {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8'));
+    const v = cfg?.task?.shortIdLength;
+    if (typeof v === 'number' && Number.isFinite(v) && v >= 1) return v;
+  } catch {
+    // fall through to default
+  }
+  return 2;
+}
+
+function resolveShortIdToTaskId(arg: string, repoRoot: string): string {
+  const scriptPath = path.join(repoRoot, '.agents', 'scripts', 'task-short-id.js');
+  if (!fs.existsSync(scriptPath)) {
+    throw new Error(`task-short-id.js not found at ${scriptPath}`);
+  }
+  const result = spawnSync('node', [scriptPath, 'resolve', arg], {
+    encoding: 'utf8',
+    cwd: repoRoot
+  });
+  if (result.status !== 0) {
+    throw new Error((result.stderr || '').trim() || `failed to resolve '${arg}'`);
+  }
+  return result.stdout.trim();
+}
+
+function listSortedNumeric(dir: string, width: number): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const pattern = new RegExp(`^\\d{${width}}$`);
+  return fs
+    .readdirSync(dir)
+    .filter((entry) => pattern.test(entry))
+    .sort()
+    .reverse();
+}
+
+function findInArchive(repoRoot: string, taskId: string): string | null {
+  // archive-tasks SKILL writes to .agents/workspace/archive/YYYY/MM/DD/{taskId}/task.md
+  // where YYYY/MM/DD comes from completed_at (or updated_at fallback) — NOT from
+  // the task id's creation date. So we cannot derive the path from taskId alone;
+  // walk the bounded YYYY/MM/DD tree instead. Newest-first to favor recent archives.
+  const archiveDir = path.join(repoRoot, '.agents', 'workspace', 'archive');
+  for (const year of listSortedNumeric(archiveDir, 4)) {
+    const yearDir = path.join(archiveDir, year);
+    for (const month of listSortedNumeric(yearDir, 2)) {
+      const monthDir = path.join(yearDir, month);
+      for (const day of listSortedNumeric(monthDir, 2)) {
+        const candidate = path.join(monthDir, day, taskId, 'task.md');
+        if (fs.existsSync(candidate)) return candidate;
+      }
+    }
+  }
+  return null;
+}
+
+function findTaskMd(repoRoot: string, taskId: string): string | null {
+  for (const sub of FLAT_WORKSPACE_DIRS) {
+    const candidate = path.join(repoRoot, '.agents', 'workspace', sub, taskId, 'task.md');
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  return findInArchive(repoRoot, taskId);
+}
+
+function show(args: string[] = []): void {
+  if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    if (args.length === 0) process.exitCode = 1;
+    return;
+  }
+  const repoRoot = detectRepoRoot();
+  const arg = args[0]!;
+  let taskId: string;
+  if (TASK_ID_RE.test(arg)) {
+    taskId = arg;
+  } else {
+    const shortIdLength = readShortIdLength(repoRoot);
+    const normalized = normalizeShortIdInput(arg, { shortIdLength });
+    if (normalized.kind === 'error') {
+      process.stderr.write(`ai task show: ${normalized.message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    if (normalized.kind === 'pass') {
+      process.stderr.write(
+        `ai task show: '${arg}' is not a valid short id or TASK-id; ` +
+          `expected bare digits, '#N', or 'TASK-YYYYMMDD-HHMMSS'\n`
+      );
+      process.exitCode = 1;
+      return;
+    }
+    try {
+      taskId = resolveShortIdToTaskId(normalized.value, repoRoot);
+    } catch (e) {
+      process.stderr.write(`ai task show: ${(e as Error).message}\n`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const taskMdPath = findTaskMd(repoRoot, taskId);
+  if (!taskMdPath) {
+    process.stderr.write(
+      `ai task show: task ${taskId} not found in active / blocked / completed / archive\n`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(fs.readFileSync(taskMdPath, 'utf8'));
+}
+
+export { show };