@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/dist/lib/platform/verification.js

@@ -0,0 +1,6 @@
+import { inspectRequiredChecks } from './pr-checks.js';
+function verificationCheck(type, status, message, failType) {
+    return { type, status, message, ...(failType ? { fail_type: failType } : {}) };
+}
+export { inspectRequiredChecks, verificationCheck };
+//# sourceMappingURL=verification.js.map

package/dist/lib/release/channels.js

@@ -0,0 +1,31 @@
+async function inspectNpmChannel(name, version, fetcher = fetch) {
+    try {
+        const response = await fetcher(`https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}`);
+        if (response.status === 404)
+            return { status: 'no-op', published: false, version, error: null };
+        if (!response.ok)
+            return { status: 'blocked', published: null, version, error: { code: 'NPM_REGISTRY_UNAVAILABLE', message: `npm registry returned ${response.status}` } };
+        const body = await response.json();
+        return { status: 'no-op', published: body.version === version, version, error: null };
+    }
+    catch (error) {
+        return { status: 'blocked', published: null, version, error: { code: 'NPM_REGISTRY_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) } };
+    }
+}
+async function inspectHomebrewChannel(url, version, fetcher = fetch) {
+    try {
+        const response = await fetcher(url);
+        if (response.status === 404)
+            return { status: 'no-op', published: false, version, error: null };
+        if (!response.ok)
+            return { status: 'blocked', published: null, version, error: { code: 'HOMEBREW_UNAVAILABLE', message: `formula endpoint returned ${response.status}` } };
+        const formula = await response.text();
+        const escaped = version.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        return { status: 'no-op', published: new RegExp(`(?:version\\s+["']${escaped}["']|/v?${escaped}\\.)`).test(formula), version, error: null };
+    }
+    catch (error) {
+        return { status: 'blocked', published: null, version, error: { code: 'HOMEBREW_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) } };
+    }
+}
+export { inspectHomebrewChannel, inspectNpmChannel };
+//# sourceMappingURL=channels.js.map

package/dist/lib/release/workflow.js

@@ -0,0 +1,32 @@
+function deriveReleasePhase(facts) {
+    if (!facts.localTag)
+        return 'unprepared';
+    if (!facts.remoteBranch && !facts.remoteTag)
+        return 'prepared';
+    if (!facts.remoteBranch || !facts.remoteTag)
+        return 'partially-published';
+    if (facts.githubRelease !== true || facts.npm !== true || facts.homebrew !== true)
+        return 'published';
+    if (facts.smoke !== 'success' || !facts.postCommit)
+        return 'post-pending';
+    return 'complete';
+}
+function releaseSnapshot(version, facts) {
+    return { version, tag: `v${version.replace(/^v/, '')}`, phase: deriveReleasePhase(facts), facts };
+}
+async function runReleaseAction(input) {
+    const before = releaseSnapshot(input.version, await input.inspect());
+    if (input.action === 'inspect')
+        return { status: 'no-op', changed: false, before, snapshot: before, error: null };
+    const allowed = input.action === 'prepare' ? before.phase === 'unprepared'
+        : input.action === 'publish' ? ['prepared', 'partially-published'].includes(before.phase)
+            : ['published', 'post-pending'].includes(before.phase);
+    if (!allowed)
+        return { status: before.phase === 'complete' ? 'no-op' : 'failed', changed: false, before, snapshot: before, error: before.phase === 'complete' ? null : { code: 'RELEASE_PHASE_INVALID', message: `Cannot ${input.action} from ${before.phase}` } };
+    await input[input.action]?.();
+    const snapshot = releaseSnapshot(input.version, await input.inspect());
+    const progressed = snapshot.phase !== before.phase;
+    return { status: progressed ? 'applied' : 'blocked', changed: progressed, before, snapshot, error: progressed ? null : { code: 'RELEASE_PROGRESS_PENDING', message: `${input.action} has not reached the next observable phase` } };
+}
+export { deriveReleasePhase, releaseSnapshot, runReleaseAction };
+//# sourceMappingURL=workflow.js.map

package/dist/lib/render.js

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
-// Add a new identifier here only after shipping matching .{platform}. template variants.
-const KNOWN_PLATFORMS = new Set(['github']);
+// Built-in platform strategies. "none" deliberately selects generic templates
+// and the no-op runtime adapter instead of requiring .none.* variants.
+const KNOWN_PLATFORMS = new Set(['github', 'none']);
 const KNOWN_LANGUAGES = new Set(['en', 'zh-CN']);
 function renderFile(src, dst, replacements) {
     if (!fs.existsSync(src)) {

package/dist/lib/run/index.js

@@ -7,14 +7,15 @@ import { loadShortIdByTaskId, normalizeShortIdInput } from '../task/short-id.js'
 import { buildTuiCommand, renderPrompt, selectTui } from './tui.js';
 import { getSkillRunSpec } from './skills.js';
 import { runHostCommand } from './host.js';
-const USAGE = `Usage: ai run <skill> [task-ref] [args...] [--tui <name>]
+const USAGE = `Usage: ai run <skill> [task-ref] [args...] [--tui <name>] [--recreate]
 
 Task skills are scheduled inside the sandbox tmux session; ai run returns once
-the tmux window is created.
+the tmux window is created. --recreate authorizes container-only replacement
+when in-place sandbox recovery fails; it is not included in the TUI prompt.
 
 Examples:
   ai run create-task "describe the task" --tui codex
-  ai run code-task #7 --tui codex`;
+  ai run code-task #7 --tui codex --recreate`;
 function extractTui(args) {
     const rest = [];
     let tui = null;
@@ -36,12 +37,16 @@ export function parseRunArgs(args) {
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
         throw new Error(USAGE);
     }
-    const { rest, tui } = extractTui(args);
+    const { rest: withRecoveryFlags, tui } = extractTui(args);
+    const recreate = withRecoveryFlags.includes('--recreate');
+    const rest = withRecoveryFlags.filter((arg) => arg !== '--recreate');
     const [skill = '', maybeTaskRef, ...remaining] = rest;
     const spec = getSkillRunSpec(skill);
     if (!spec)
         throw new Error(`Unknown skill '${skill}'`);
     if (spec.kind === 'create') {
+        if (recreate)
+            throw new Error('--recreate is only valid for sandbox task runs');
         const createArgs = rest.slice(1);
         if (createArgs.length === 0)
             throw new Error('create-task requires a description');
@@ -49,7 +54,13 @@ export function parseRunArgs(args) {
     }
     if (!maybeTaskRef)
         throw new Error(`${skill} requires a task-ref`);
-    return { skill, taskRef: maybeTaskRef, args: remaining, tui };
+    return {
+        skill,
+        taskRef: maybeTaskRef,
+        args: remaining,
+        tui,
+        ...(recreate ? { recreate: true } : {})
+    };
 }
 function assertAllowedByConfig(skill, commandConfig) {
     const allowed = commandConfig.allowedSkills;
@@ -97,7 +108,7 @@ function resolveActiveTaskIdentity(taskRef, repoRoot) {
         if (normalized.kind !== 'shortId')
             return null;
         resolvedTaskRef = normalized.value;
-        taskId = readActiveShortIdRegistry(repoRoot)[normalized.value.slice(1)] ?? null;
+        taskId = readActiveShortIdRegistry(repoRoot)[normalized.value] ?? null;
     }
     if (!taskId)
         return null;
@@ -161,7 +172,13 @@ export async function runSkill(args, options = {}) {
     const writeStderr = options.writeStderr ?? ((chunk) => process.stderr.write(chunk));
     const runSandbox = options.runSandbox ??
         ((request) => runInSandbox(request));
-    const result = await runSandbox({ taskRef: parsed.taskRef, branch, command, runId });
+    const result = await runSandbox({
+        taskRef: parsed.taskRef,
+        branch,
+        command,
+        runId,
+        recreate: parsed.recreate
+    });
     if (result.stdout) {
         writeStdout(result.stdout);
     }

package/dist/lib/sandbox/capture.js

@@ -3,6 +3,7 @@ import { loadConfig } from './config.js';
 import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.js';
 import { detectEngine } from './engine.js';
 import { commandForEngine } from './shell.js';
+import { ensureSandboxReady } from './recovery.js';
 import { hostTimezoneEnvFlags, terminalEnvFlags } from './commands/enter.js';
 import { fetchSandboxRows, selectSandboxContainer, startSandboxContainer } from './commands/list-running.js';
 async function spawnCapture(file, args) {
@@ -131,7 +132,28 @@ export async function runInSandbox(request, options = {}) {
     if (!found) {
         throw new Error(`Sandbox for ${request.branch} not found. Create it first with ai sandbox create ${request.taskRef}.`);
     }
-    if (!found.running) {
+    let container = found.name;
+    if (options.ensureReady) {
+        container = (await options.ensureReady({
+            branch: request.branch,
+            row: found,
+            allowRecreate: request.recreate ?? false
+        })).container;
+    }
+    else if (config) {
+        container = (await ensureSandboxReady({
+            config,
+            engine,
+            branch: request.branch,
+            row: found,
+            allowRecreate: request.recreate,
+            recreate: async (targetBranch) => {
+                const { create } = await import('./commands/create.js');
+                await create([targetBranch, '--no-refresh']);
+            }
+        })).container;
+    }
+    else if (!found.running) {
         (options.startContainer ?? ((name) => startSandboxContainer(engine, name)))(found.name);
     }
     const runId = options.runId ?? createRunId();
@@ -140,7 +162,7 @@ export async function runInSandbox(request, options = {}) {
         'exec',
         ...terminalEnvFlags(),
         ...hostTimezoneEnvFlags(),
-        found.name,
+        container,
         'bash',
         '-lc',
         buildTmuxLauncher({ request, runId })
@@ -152,7 +174,7 @@ export async function runInSandbox(request, options = {}) {
         run: {
             runId,
             engine,
-            container: found.name,
+            container,
             runDir
         }
     };

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

@@ -13,8 +13,10 @@ import { prepareDockerfile } from '../dockerfile.js';
 import { detectEngine, ensureDocker } from '../engine.js';
 import { commandForEngine, execEngine, run, runEngine, runOk, runOkEngine, runSafe, runSafeEngine, runVerboseEngine } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
-import { resolveTools, toolConfigDirCandidates } from '../tools.js';
+import { resolveTools, tmpfsSeedStagingPath, tmpfsSeedTargetPath, toolConfigDirCandidates } from '../tools.js';
+import { assertFreshSandboxReady, hydrateTmpfsSeedEntries, prepareTmpfsMounts } from '../recovery.js';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
+import { sandboxCoreBindMounts } from '../mounts.js';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.js';
 import { validateSelinuxDisableEnv } from '../engines/selinux.js';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
@@ -999,6 +1001,7 @@ export async function create(args) {
     const baseBranch = base ?? runSafe('git', ['-C', effectiveConfig.repoRoot, 'branch', '--show-current']);
     const expectedImageSignature = buildImageSignature(preparedDockerfile, tools);
     const engine = detectEngine(effectiveConfig);
+    let createdTmpfsSeedPlan = [];
     p.intro(pc.cyan('AI Sandbox'));
     p.log.info(`Project: ${pc.bold(effectiveConfig.project)} | Branch: ${pc.bold(branch)} | Base: ${pc.bold(baseBranch || 'HEAD')}`);
     if (credentialOutcome.status === 'SKIPPED') {
@@ -1209,9 +1212,12 @@ export async function create(args) {
                             branch,
                             repoRoot: effectiveConfig.repoRoot
                         });
-                        const shellConfigVolumes = hostShellConfig.mounts.flatMap(({ hostPath, containerPath }) => [
+                        const coreVolumes = sandboxCoreBindMounts(effectiveConfig, branch, {
+                            worktree,
+                            shellConfigHostDir: hostShellConfig.hostDir
+                        }).flatMap(({ hostPaths, containerPath, readOnly }) => [
                             '-v',
-                            volumeArg(engine, hostPath, containerPath, ':ro')
+                            volumeArg(engine, hostPaths[0], containerPath, readOnly ? ':ro' : '')
                         ]);
                         // Mount each declared seed read-only at an isolated staging path.
                         // After docker run mounts the empty tmpfs, the container's default
@@ -1220,14 +1226,17 @@ export async function create(args) {
                         // stale runtime files (logs_2.sqlite, sessions, etc.) on the host from
                         // being exposed or written through.
                         tmpfsSeedPlan = effectiveResolvedTools.flatMap(({ tool, dir }) => (tool.tmpfs?.seed ?? []).flatMap((entry, index) => {
+                            const targetPath = tmpfsSeedTargetPath(tool.containerMount, entry);
                             const hostPath = path.join(dir, entry);
                             if (!fs.existsSync(hostPath)) {
                                 return [];
                             }
-                            const stagingPath = path.posix.join('/run/agent-infra/tmpfs-seeds', tool.id, String(index));
+                            const stagingPath = tmpfsSeedStagingPath(tool.id, index);
                             return [{
+                                    toolId: tool.id,
+                                    containerMount: tool.containerMount,
                                     stagingPath,
-                                    targetPath: path.posix.join(tool.containerMount, entry),
+                                    targetPath,
                                     volumeArgs: ['-v', volumeArg(engine, hostPath, stagingPath, ':ro')]
                                 }];
                         }));
@@ -1258,14 +1267,7 @@ export async function create(args) {
                             sandboxLabel(effectiveConfig),
                             '--label',
                             `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
-                            '-v',
-                            volumeArg(engine, worktree, '/workspace'),
-                            '-v',
-                            volumeArg(engine, workspaceDir, '/workspace/.agents/workspace'),
-                            '-v',
-                            volumeArg(engine, shareCommon, '/share/common'),
-                            '-v',
-                            volumeArg(engine, shareBranch, '/share/branch'),
+                            ...coreVolumes,
                             ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
                             '-v',
                             volumeArg(engine, path.join(effectiveConfig.repoRoot, '.git'), `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`),
@@ -1274,25 +1276,30 @@ export async function create(args) {
                             ...tmpfsArgs,
                             ...tmpfsSeedPlan.flatMap(({ volumeArgs }) => volumeArgs),
                             ...liveMountVolumes,
-                            ...shellConfigVolumes,
                             ...envFile.dockerArgs,
                             ...tzFlags,
                             '-w',
                             '/workspace',
                             effectiveConfig.imageName
                         ]);
+                        createdTmpfsSeedPlan = tmpfsSeedPlan;
                     }
                     finally {
                         envFile.cleanup();
                     }
-                    for (const { stagingPath, targetPath } of tmpfsSeedPlan) {
-                        runEngineTaskCommand(engine, 'docker', [
-                            'exec', container, 'mkdir', '-p', path.posix.dirname(targetPath)
-                        ]);
-                        runEngineTaskCommand(engine, 'docker', [
-                            'exec', container, 'cp', '-R', '--', stagingPath, targetPath
-                        ]);
-                    }
+                    prepareTmpfsMounts({
+                        engine,
+                        container,
+                        mountPaths: effectiveResolvedTools
+                            .filter(({ tool }) => tool.tmpfs)
+                            .map(({ tool }) => tool.containerMount)
+                    });
+                    hydrateTmpfsSeedEntries({
+                        engine,
+                        container,
+                        entries: tmpfsSeedPlan,
+                        replace: true
+                    });
                     // Belt-and-suspenders: re-create the four shell-config symlinks at
                     // runtime so users with a custom `sandbox.dockerfile` (which won't
                     // include the ai-tools.dockerfile symlink fragment) still get
@@ -1346,6 +1353,13 @@ export async function create(args) {
         preparedDockerfile.cleanup();
     }
     p.log.step('Verifying setup...');
+    assertFreshSandboxReady({
+        config: effectiveConfig,
+        engine,
+        branch,
+        container,
+        copiedEntries: createdTmpfsSeedPlan
+    });
     const runningContainers = runSafeEngine(engine, 'docker', ['ps', '--format', '{{.Names}}']).split('\n');
     const checks = [
         { name: 'Container running', ok: runningContainers.includes(container) },

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

@@ -1,18 +1,20 @@
 import { loadConfig } from '../config.js';
 import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.js';
 import { detectEngine } from '../engine.js';
+import { ensureSandboxReady } from '../recovery.js';
 import { formatCredentialWarnings, formatRemaining, hasClaudeProviderAuth, reconcileClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from '../credentials.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 { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, startSandboxContainer } from './list-running.js';
-const USAGE = `Usage: ai sandbox exec <branch | TASK-id | N | '#N'> [cmd...]
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, } from './list-running.js';
+const USAGE = `Usage: ai sandbox exec [--recreate] <branch | TASK-id | N> [cmd...]
 
-N (bare) and '#N' both reference the same active task short id from
+N references an 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.`;
+'ai sandbox ls' output. --recreate is a host recovery flag only before the
+target; the same token after the target is passed to the container command.`;
 const TMUX_ENTRY_PATH = '/usr/local/bin/sandbox-tmux-entry';
 // Terminal-detection variables that interactive TUIs (e.g. claude-code)
 // inspect to enable progressive enhancements such as the kitty keyboard
@@ -76,6 +78,19 @@ export function formatCredentialSyncStatus(result, isTTY = process.stderr.isTTY,
     }
     return null;
 }
+export function parseEnterArgs(args) {
+    let recreate = false;
+    let index = 0;
+    while (args[index] === '--recreate') {
+        recreate = true;
+        index += 1;
+    }
+    const target = args[index] ?? '';
+    if (!target) {
+        throw new Error(USAGE);
+    }
+    return { target, command: args.slice(index + 1), recreate };
+}
 export async function enter(args) {
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(`${USAGE}\n`);
@@ -87,19 +102,27 @@ export async function enter(args) {
     const config = loadConfig();
     validateClaudeCredentialsEnvOverride();
     const engine = detectEngine(config);
-    const [firstArg = '', ...cmd] = args;
-    const branch = resolveBranchArg(firstArg, { repoRoot: config.repoRoot });
+    const parsed = parseEnterArgs(args);
+    const branch = resolveBranchArg(parsed.target, { 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 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;
+    const ready = await ensureSandboxReady({
+        config,
+        engine,
+        branch,
+        row: found,
+        allowRecreate: parsed.recreate,
+        recreate: async (targetBranch) => {
+            const { create } = await import('./create.js');
+            await create([targetBranch, '--no-refresh']);
+        }
+    });
+    const container = ready.container;
+    const cmd = parsed.command;
     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

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { runSafeEngine, runVerboseEngine } from '../shell.js';
 import { resolveTaskBranch } from '../task-resolver.js';
+import { isRemovedHashShortIdInput } from '../../task/short-id.js';
 export function containerListFormat() {
     return '{{.Names}}\t{{.Status}}\t{{.Labels}}';
 }
@@ -70,13 +71,13 @@ export function fetchSandboxRows(engine, label, branchKey) {
 }
 /**
  * Returns true iff `arg` is a syntactically valid task short reference.
- * Accepts both bare numeric ('11') and '#'-prefixed ('#11') forms.
+ * Accepts bare numeric ('11') task short ids.
  * Zero IO. Callers MUST use this as the gate before constructing any context
  * for resolveTaskShortRef — that way non-matching arguments (e.g. '#abc',
  * '#1.5', '#') never trigger sandbox list IO.
  */
 export function isTaskShortRef(arg) {
-    return /^#?\d+$/.test(arg);
+    return /^\d+$/.test(arg);
 }
 /**
  * Try to resolve a short ref against the global task-short-id registry.
@@ -91,9 +92,7 @@ function tryResolveFromRegistry(arg, repoRoot) {
     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.)
+    // Forward the bare-numeric short ref to the registry script for ID resolution.
     const result = spawnSync('node', [scriptPath, 'resolve', arg], { encoding: 'utf8', cwd: repoRoot });
     if (result.status !== 0)
         return { status: 'miss' };
@@ -120,7 +119,7 @@ function tryResolveFromRegistry(arg, repoRoot) {
 }
 /**
 /**
- * Resolve a task short reference (bare 'N' or '#N') to a branch name for the
+ * Resolve a bare task short reference to a branch name for the
  * sandbox entrypoint.
  *
  * Resolution: registry-only. Look up the short id in the global task-short-id
@@ -137,11 +136,11 @@ export function resolveTaskShortRef(arg, ctx) {
     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'); ` +
+        `bare N resolves 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
+ * Resolve a sandbox command argument (`<branch | TASK-id | 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
@@ -149,6 +148,9 @@ export function resolveTaskShortRef(arg, ctx) {
  * Callers still run assertValidBranchName on the result.
  */
 export function resolveBranchArg(arg, ctx) {
+    if (isRemovedHashShortIdInput(arg)) {
+        throw new Error(`Invalid task short id '${arg}': task short ids must use bare digits`);
+    }
     return isTaskShortRef(arg)
         ? resolveTaskShortRef(arg, ctx)
         : resolveTaskBranch(arg, ctx.repoRoot);

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

@@ -5,12 +5,12 @@ import { loadConfig } from '../config.js';
 import { assertValidBranchName, worktreeDirCandidates } from '../constants.js';
 import { resolveBranchArg } from './list-running.js';
 import { resolveTools, toolConfigDirCandidates } from '../tools.js';
-const USAGE = `Usage: ai sandbox show <branch | TASK-id | N | '#N'>
+const USAGE = `Usage: ai sandbox show <branch | TASK-id | N>
 
 Shows one sandbox's worktree path and per-tool state paths (Claude Code,
 Codex, Gemini CLI, OpenCode). The argument follows the same contract as
 'ai sandbox exec' and 'ai sandbox start': N (bare) is the recommended form
-for task short ids (e.g. 'ai sandbox show 11'); '#N', a TASK-id, or a plain
+for task short ids (e.g. 'ai sandbox show 11'); a TASK-id or a plain
 branch name are also accepted. Use 'ai sandbox ls' for the container list.`;
 function existingDirs(candidates) {
     const seen = new Set();

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

@@ -1,36 +1,74 @@
 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'>
+import { ensureSandboxReady } from '../recovery.js';
+import { fetchSandboxRows, resolveBranchArg, selectSandboxContainer, } from './list-running.js';
+const USAGE = `Usage: ai sandbox start [--recreate] <branch | TASK-id | 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.`;
+already running is checked without modifying healthy runtime state. --recreate
+allows container-only replacement after in-place recovery fails.`;
+export function parseStartArgs(args) {
+    let recreate = false;
+    let help = false;
+    const positionals = [];
+    for (const arg of args) {
+        if (arg === '--recreate') {
+            recreate = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            help = true;
+        }
+        else if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}\n${USAGE}`);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    if (!help && positionals.length !== 1) {
+        throw new Error(USAGE);
+    }
+    return { target: positionals[0] ?? '', recreate, help };
+}
 export async function start(args) {
-    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+    if (args.length === 0) {
+        process.stdout.write(`${USAGE}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    const parsed = parseStartArgs(args);
+    if (parsed.help) {
         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 });
+    const branch = resolveBranchArg(parsed.target, { 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`);
+    const ready = await ensureSandboxReady({
+        config,
+        engine,
+        branch,
+        row: found,
+        allowRecreate: parsed.recreate,
+        recreate: async (targetBranch) => {
+            const { create } = await import('./create.js');
+            await create([targetBranch, '--no-refresh']);
+        }
+    });
+    const message = ready.path === 'healthy'
+        ? `Sandbox '${ready.container}' is already running and healthy.`
+        : ready.path === 'recreated'
+            ? `Recreated sandbox '${ready.container}' and verified readiness.`
+            : `Recovered sandbox '${ready.container}' and verified readiness.`;
+    process.stdout.write(`${message}\n`);
 }
 //# sourceMappingURL=start.js.map

package/dist/lib/sandbox/index.js

@@ -2,14 +2,14 @@ const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
   create <branch> [base]       Create a sandbox (VM + image + worktree + container)
-  exec <branch | TASK-id | N | '#N'> [cmd...]
+  exec [--recreate] <branch | TASK-id | 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.
+                               'ai sandbox exec 11').
   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)
-  show <branch | TASK-id | N | '#N'>
+  show <branch | TASK-id | N>
                                Show one sandbox's worktree and per-tool state paths
   prune [--dry-run]            Remove orphaned per-branch state dirs
   rebuild [--quiet] [--refresh]
@@ -18,9 +18,9 @@ Commands:
   rm <branch> | --all | --purge
                                Remove one sandbox, all sandboxes not bound to an
                                active task (--all), or tear down everything (--purge)
-  start <branch | TASK-id | N | '#N'>
-                               Start an existing stopped sandbox container
-                               (e.g. after the Docker daemon restarted)
+  start [--recreate] <branch | TASK-id | N>
+                               Verify or recover an existing sandbox container;
+                               optionally replace only the container on failure
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;