@fitlab-ai/agent-infra 0.7.1 → 0.7.2

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

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const REGISTRY_NAME = '.short-ids.json';
+function normalizeShortIdInput(input, opts) {
+    const L = opts.shortIdLength;
+    const m = /^#?(\d+)$/.exec(input);
+    if (!m) {
+        return { kind: 'pass', value: input };
+    }
+    const n = Number(m[1]);
+    if (n === 0) {
+        return {
+            kind: 'error',
+            message: `short id '${input}' is invalid (#${'0'.repeat(L)} is reserved)`
+        };
+    }
+    const max = Math.pow(10, L) - 1;
+    if (n > max) {
+        return {
+            kind: 'error',
+            message: `short id ${n} exceeds shortIdLength=${L} capacity (max=${max}); archive tasks or raise task.shortIdLength in .agents/.airc.json`
+        };
+    }
+    return { kind: 'shortId', value: `#${String(n).padStart(L, '0')}` };
+}
+function readRegistry(repoRoot) {
+    const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+    if (!fs.existsSync(registryPath))
+        return null;
+    try {
+        const raw = fs.readFileSync(registryPath, 'utf8');
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== 'object' || !data.ids)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+function readBranchFromTaskMd(repoRoot, taskId) {
+    const taskMdPath = path.join(repoRoot, '.agents', 'workspace', 'active', taskId, 'task.md');
+    if (!fs.existsSync(taskMdPath))
+        return null;
+    const content = fs.readFileSync(taskMdPath, 'utf8');
+    const m = content.match(/^branch:\s*(.+)$/m);
+    if (!m || !m[1])
+        return null;
+    return m[1].trim().replace(/^(["'])(.*)\1$/, '$2');
+}
+function loadShortIdByTaskId(repoRoot) {
+    const registry = readRegistry(repoRoot);
+    const map = new Map();
+    if (!registry)
+        return map;
+    for (const [key, taskId] of Object.entries(registry.ids)) {
+        map.set(taskId, `#${key}`);
+    }
+    return map;
+}
+function lookupShortIdByBranch(branch, repoRoot, _opts) {
+    const registry = readRegistry(repoRoot);
+    if (!registry)
+        return null;
+    const matches = [];
+    for (const [key, taskId] of Object.entries(registry.ids)) {
+        const taskBranch = readBranchFromTaskMd(repoRoot, taskId);
+        if (taskBranch && taskBranch === branch) {
+            matches.push(`#${key}`);
+        }
+    }
+    if (matches.length === 0)
+        return null;
+    if (matches.length > 1) {
+        process.stderr.write(`Warning: branch '${branch}' is bound to multiple active tasks: ${matches.join(', ')}; using ${matches[0]}\n`);
+    }
+    return matches[0];
+}
+export { normalizeShortIdInput, lookupShortIdByBranch, loadShortIdByTaskId };
+//# sourceMappingURL=short-id.js.map

package/lib/sandbox/commands/create.ts

@@ -868,13 +868,22 @@ export function ensureCodexModelInheritance(toolDir: string, hostHomeDir?: strin
     }
   }
 
+  const inheritSpecs: Array<readonly [string, 'string' | 'number']> = [
+    ['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/lib/sandbox/commands/enter.ts

@@ -1,5 +1,5 @@
 import { loadConfig } from '../config.ts';
-import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.ts';
+import { assertValidBranchName, containerNameCandidates } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import {
   formatCredentialWarnings,
@@ -13,12 +13,14 @@ import { resolveTaskBranch } from '../task-resolver.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.ts';
 import { detectHostTimezone } from '../host-timezone.ts';
-import { fetchSandboxRows, isTaskShortRef, resolveTaskShortRef } from './list-running.ts';
+import { isTaskShortRef, resolveTaskShortRef } from './list-running.ts';
 
-const USAGE = `Usage: ai sandbox exec <branch | TASK-id | '#N'> [cmd...]
+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)
@@ -122,8 +124,7 @@ export async function enter(args: string[]): Promise<number> {
   const [firstArg = '', ...cmd] = args;
   let branch: string;
   if (isTaskShortRef(firstArg)) {
-    const { running } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
-    branch = resolveTaskShortRef(firstArg, { running, repoRoot: config.repoRoot });
+    branch = resolveTaskShortRef(firstArg, { repoRoot: config.repoRoot });
   } else {
     branch = resolveTaskBranch(firstArg, config.repoRoot);
   }

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

@@ -88,13 +88,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 +114,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 +146,29 @@ 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.
-  }
-  return resolveByRunningIndex(arg, ctx.running);
+  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.`
+  );
 }

package/lib/sandbox/commands/ls.ts

@@ -6,40 +6,35 @@ 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').`;
 
-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))
-  ];
+  return formatTable(
+    CONTAINER_TABLE_HEADERS,
+    rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch])
+  );
 }
 
 function listChildren(dir: string): string[] {
@@ -69,15 +64,20 @@ 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
-    }));
+    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)) {
       process.stdout.write(`  ${line}\n`);
     }
+    process.stdout.write(`  Total: ${ordered.length} containers\n`);
   }
 
   p.log.step('Worktrees');

package/lib/sandbox/index.ts

@@ -2,9 +2,13 @@ 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.
+  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)

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,32 @@
+function formatTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[]
+): string[] {
+  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();
+  };
+
+  return [renderRow(headers), ...rows.map((row) => renderRow(row))];
+}
+
+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)) {
+    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 };