@fitlab-ai/agent-infra 0.7.2 → 0.7.4

package/bin/cli.ts

@@ -18,7 +18,7 @@ Usage:
   agent-infra init            Initialize a new project with update-agent-infra seed command
   agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
   agent-infra sandbox         Manage Docker-based AI sandboxes
-  agent-infra task            Read-only views over .agents/workspace tasks (ls / show)
+  agent-infra task            Read-only views over .agents/workspace tasks (ls / show / files / cat / status / log / grep)
   agent-infra update          Update seed files and sync file registry for an existing project
   agent-infra version         Show version
 

package/dist/bin/cli.js

@@ -22,7 +22,7 @@ Usage:
   agent-infra init            Initialize a new project with update-agent-infra seed command
   agent-infra merge           Merge tasks from another workspace directory (active/blocked/completed/archive)
   agent-infra sandbox         Manage Docker-based AI sandboxes
-  agent-infra task            Read-only views over .agents/workspace tasks (ls / show)
+  agent-infra task            Read-only views over .agents/workspace tasks (ls / show / files / cat / status / log / grep)
   agent-infra update          Update seed files and sync file registry for an existing project
   agent-infra version         Show version
 

package/dist/lib/defaults.json

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

package/dist/lib/init.js

@@ -158,8 +158,6 @@ async function cmdInit() {
         info(`Custom platform '${platformType}' selected. Built-in templates are only complete for github;`
             + ` provide matching '.${platformType}.' or generic templates before running update-agent-infra.`);
     }
-    const requiresPRChoice = await select('Require Pull Request flow?', ['yes', 'no'], 'yes');
-    const requiresPullRequest = requiresPRChoice !== 'no';
     let enabledTUIs;
     try {
         enabledTUIs = await multiSelect('Built-in TUI command files to install/manage', BUILTIN_TUI_IDS.map((id) => ({ id, label: BUILTIN_TUI_DISPLAY[id] })));
@@ -220,7 +218,6 @@ async function cmdInit() {
         org: orgName,
         language,
         platform: { type: platformType },
-        requiresPullRequest,
         templateVersion: VERSION,
         sandbox: structuredClone(defaults.sandbox),
         task: structuredClone(defaults.task),

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

@@ -604,7 +604,32 @@ export function ensureClaudeSettings(toolDir, hostHomeDir) {
         fs.writeFileSync(settingsPath, JSON.stringify(data, null, 4), 'utf8');
     }
 }
-export function ensureCodexModelInheritance(toolDir, hostHomeDir) {
+function resolveHostCatalogPath(value, hostHomeDir) {
+    if (typeof value !== 'string' || value === '') {
+        return null;
+    }
+    let resolved;
+    if (value === '~' || value.startsWith('~/') || value.startsWith('~\\')) {
+        resolved = path.join(hostHomeDir, value.slice(1).replace(/^[/\\]+/, ''));
+    }
+    else if (path.isAbsolute(value)) {
+        resolved = value;
+    }
+    else {
+        resolved = path.join(hostHomeDir, '.codex', value);
+    }
+    try {
+        if (!fs.statSync(resolved).isFile()) {
+            return null;
+        }
+        fs.accessSync(resolved, fs.constants.R_OK);
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+export function ensureCodexModelInheritance(toolDir, hostHomeDir, containerCodexDir = '/home/devuser/.codex') {
     if (!hostHomeDir) {
         return;
     }
@@ -650,6 +675,22 @@ export function ensureCodexModelInheritance(toolDir, hostHomeDir) {
         sandboxParsed[key] = value;
         changed = true;
     }
+    if (!Object.hasOwn(sandboxParsed, 'model_catalog_json')) {
+        const hostCatalogPath = resolveHostCatalogPath(hostParsed['model_catalog_json'], hostHomeDir);
+        if (hostCatalogPath) {
+            try {
+                const basename = path.basename(hostCatalogPath);
+                const destDir = path.join(toolDir, 'model-catalogs');
+                fs.mkdirSync(destDir, { recursive: true });
+                fs.copyFileSync(hostCatalogPath, path.join(destDir, basename));
+                sandboxParsed['model_catalog_json'] = path.posix.join(containerCodexDir, 'model-catalogs', basename);
+                changed = true;
+            }
+            catch {
+                // Copy failed (e.g. permissions): skip catalog, keep scalar inheritance intact.
+            }
+        }
+    }
     if (changed) {
         fs.writeFileSync(sandboxConfigPath, `${toml.stringify(sandboxParsed)}\n`, 'utf8');
     }
@@ -780,7 +821,7 @@ function runEngineTaskCommand(engine, cmd, args, opts = {}) {
     return runTaskCommand(command.cmd, command.args, opts);
 }
 export function buildImage(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, runVerboseFn = runVerboseEngine, env = process.env } = {}) {
-    const selectedEngine = engine ?? detectEngine(config);
+    const selectedEngine = engine ?? detectEngine({ engine: config.engine });
     const { uid: hostUid, gid: hostGid } = resolveBuildUid({
         engine: selectedEngine,
         runFn,
@@ -1023,7 +1064,7 @@ export async function create(args) {
                         }
                         const codexEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'codex');
                         if (codexEntry) {
-                            ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home);
+                            ensureCodexModelInheritance(codexEntry.dir, effectiveConfig.home, codexEntry.tool.containerMount);
                             ensureCodexWorkspaceTrust(codexEntry.dir);
                         }
                         const geminiEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'gemini-cli');

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

@@ -1,13 +1,12 @@
 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";
-import { resolveTaskBranch } from "../task-resolver.js";
+import { runInteractiveEngine } from "../shell.js";
 import { dotfilesCacheDir, materializeDotfiles } from "../dotfiles.js";
 import { runInteractiveWithClipboardBridge } from "../clipboard/bridge.js";
 import { detectHostTimezone } from "../host-timezone.js";
-import { isTaskShortRef, resolveTaskShortRef } from "./list-running.js";
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, startSandboxContainer } from "./list-running.js";
 const USAGE = `Usage: ai sandbox exec <branch | TASK-id | N | '#N'> [cmd...]
 
 N (bare) and '#N' both reference the same active task short id from
@@ -86,19 +85,18 @@ export async function enter(args) {
     validateClaudeCredentialsEnvOverride();
     const engine = detectEngine(config);
     const [firstArg = '', ...cmd] = args;
-    let branch;
-    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 {
             // Scan all projects so a refresh from a neighbouring sandbox can still flow back to the host.

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

@@ -1,7 +1,8 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { runSafeEngine } from "../shell.js";
+import { runSafeEngine, runVerboseEngine } from "../shell.js";
+import { resolveTaskBranch } from "../task-resolver.js";
 export function containerListFormat() {
     return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
 }
@@ -139,4 +140,38 @@ export function resolveTaskShortRef(arg, ctx) {
         `'#N' and bare N resolve only via the registry (not by row position in 'ai sandbox ls'); ` +
         `use a task short id (e.g. 'ai sandbox exec 11'), a TASK-id, or a branch name.`);
 }
+/**
+ * Resolve a sandbox command argument (`<branch | TASK-id | N | '#N'>`) to a
+ * branch name, mirroring `ai sandbox exec` so that `start` and `exec` share one
+ * input contract. Short refs go through the registry-only resolver (which throws
+ * an actionable error on a miss); everything else flows through resolveTaskBranch
+ * (plain branch names pass through unchanged, TASK-ids resolve via task.md).
+ * Callers still run assertValidBranchName on the result.
+ */
+export function resolveBranchArg(arg, ctx) {
+    return isTaskShortRef(arg)
+        ? resolveTaskShortRef(arg, ctx)
+        : resolveTaskBranch(arg, ctx.repoRoot);
+}
+/**
+ * Pick the sandbox container row whose name matches one of the candidate
+ * container names (covers both the '..' and legacy '-' branch sanitizations).
+ * Pure: no IO. Returns null when no row matches.
+ */
+export function selectSandboxContainer(rows, candidates) {
+    return rows.find((row) => candidates.includes(row.name)) ?? null;
+}
+/**
+ * Start an existing (stopped) sandbox container by name. Throws a distinct,
+ * actionable error when `docker start` fails, so callers can tell "start failed"
+ * apart from "container not found".
+ */
+export function startSandboxContainer(engine, name) {
+    try {
+        runVerboseEngine(engine, 'docker', ['start', name]);
+    }
+    catch (error) {
+        throw new Error(`Failed to start sandbox container '${name}': ${error instanceof Error ? error.message : 'unknown error'}`);
+    }
+}
 //# sourceMappingURL=list-running.js.map

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

@@ -16,10 +16,12 @@ 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'];
-export function formatContainerTable(rows) {
-    return formatTable(CONTAINER_TABLE_HEADERS, rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch]));
+export function formatContainerTable(rows, zebra = false) {
+    return formatTable(CONTAINER_TABLE_HEADERS, rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch]), { zebra });
 }
 function listChildren(dir) {
     if (!fs.existsSync(dir)) {
@@ -54,10 +56,13 @@ export function ls(args = []) {
                 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');
     const worktrees = listChildren(config.worktreeBase);

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

@@ -11,12 +11,17 @@ import { removeManagedDir, removeWorktreeDir } from "../managed-fs.js";
 import { runOk, runSafe, runSafeEngine } from "../shell.js";
 import { resolveTaskBranch } from "../task-resolver.js";
 import { resolveTools, toolConfigDirCandidates, toolProjectDirCandidates } from "../tools.js";
-const USAGE = `Usage: ai sandbox rm <branch> [--all]`;
+import { fetchSandboxRows } from "./list-running.js";
+import { lookupShortIdByBranch } from "../../task/short-id.js";
+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.js";
 function projectToolDirs(config, tools) {
     return tools.flatMap((tool) => toolProjectDirCandidates(tool, config.project));
 }
-async function rmOne(config, tools, branch) {
+async function rmOne(config, tools, branch, options = {}) {
     assertValidBranchName(branch);
     const engine = detectEngine(config);
     let effectiveBranch = branch;
@@ -25,7 +30,9 @@ async function rmOne(config, tools, branch) {
         tool,
         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)
         .filter((name) => existing.includes(name));
@@ -57,10 +64,12 @@ async function rmOne(config, tools, branch) {
     }
     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');
             return;
@@ -69,10 +78,12 @@ async function rmOne(config, tools, branch) {
             for (const worktree of existingWorktrees) {
                 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])) {
                     p.log.warn(`Local branch '${effectiveBranch}' was not deleted`);
@@ -92,18 +103,22 @@ async function rmOne(config, tools, branch) {
     }
     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, tools) {
+async function rmPurge(config, tools) {
     const engine = detectEngine(config);
     p.intro(pc.cyan(`Removing all sandboxes for ${config.project}`));
     const containers = runSafeEngine(engine, 'docker', [
@@ -193,6 +208,52 @@ async function rmAll(config, tools) {
     }
     p.outro(pc.green('All project sandboxes removed'));
 }
+async function rmUnbound(config, tools, options) {
+    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 = [];
+    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) {
     const { values, positionals } = parseArgs({
         args,
@@ -200,6 +261,9 @@ export async function rm(args) {
         strict: true,
         options: {
             all: { type: 'boolean' },
+            purge: { type: 'boolean' },
+            'dry-run': { type: 'boolean' },
+            yes: { type: 'boolean', short: 'y' },
             help: { type: 'boolean', short: 'h' }
         }
     });
@@ -207,13 +271,29 @@ export async function rm(args) {
         process.stdout.write(`${USAGE}\n`);
         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;
     }
     const branch = resolveTaskBranch(positionals[0] ?? '', config.repoRoot);

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

@@ -0,0 +1,36 @@
+import { loadConfig } from "../config.js";
+import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from "../constants.js";
+import { detectEngine } from "../engine.js";
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, startSandboxContainer } from "./list-running.js";
+const USAGE = `Usage: ai sandbox start <branch | TASK-id | N | '#N'>
+
+Start an existing sandbox container that has stopped (for example after the
+Docker daemon was restarted or replaced). The container must already exist:
+if none is found, run 'ai sandbox create <branch>' first. A container that is
+already running is left untouched.`;
+export async function start(args) {
+    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(`${USAGE}\n`);
+        if (args.length === 0) {
+            process.exitCode = 1;
+        }
+        return;
+    }
+    const [firstArg = ''] = args;
+    const config = loadConfig();
+    const engine = detectEngine(config);
+    const branch = resolveBranchArg(firstArg, { repoRoot: config.repoRoot });
+    assertValidBranchName(branch);
+    const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+    const found = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, branch));
+    if (!found) {
+        throw new Error(`No sandbox container for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`);
+    }
+    if (found.running) {
+        process.stdout.write(`Sandbox '${found.name}' is already running.\n`);
+        return;
+    }
+    startSandboxContainer(engine, found.name);
+    process.stdout.write(`Started sandbox '${found.name}'.\n`);
+}
+//# sourceMappingURL=start.js.map

package/dist/lib/sandbox/index.js

@@ -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.`;
@@ -50,6 +55,11 @@ export async function runSandbox(args) {
             }
             break;
         }
+        case 'start': {
+            const { start } = await import("./commands/start.js");
+            await start(rest);
+            break;
+        }
         case 'ls': {
             const { ls } = await import("./commands/ls.js");
             ls(rest);

package/dist/lib/sandbox/readme-scaffold.js

@@ -9,7 +9,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:
 
@@ -37,7 +37,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-通道
 
 常见用法：把文件或符号链接放进来：
 
@@ -62,7 +62,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.
 
@@ -73,7 +73,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\` 会重新生成。
 `;
@@ -83,7 +83,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.
 
@@ -94,7 +94,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/dist/lib/table.js

@@ -1,4 +1,6 @@
-function formatTable(headers, rows) {
+import pc from 'picocolors';
+function formatTable(headers, rows, options = {}) {
+    const { zebra = false } = options;
     const columnCount = headers.length;
     const widths = headers.map((header, i) => {
         const headerLen = header.length;
@@ -23,7 +25,14 @@ function formatTable(headers, rows) {
         }
         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 };
 //# sourceMappingURL=table.js.map

package/dist/lib/task/artifacts.js

@@ -0,0 +1,58 @@
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * 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) {
+    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, artifactOrN) {
+    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 };
+//# sourceMappingURL=artifacts.js.map