@fitlab-ai/agent-infra 0.8.5 → 0.9.0

package/lib/platform/verification.ts

@@ -0,0 +1,11 @@
+import { inspectRequiredChecks } from './pr-checks.ts';
+
+type VerificationStatus = 'pass' | 'fail' | 'blocked';
+type VerificationCheck = { type: string; status: VerificationStatus; message: string; fail_type?: string };
+
+function verificationCheck(type: string, status: VerificationStatus, message: string, failType?: string): VerificationCheck {
+  return { type, status, message, ...(failType ? { fail_type: failType } : {}) };
+}
+
+export { inspectRequiredChecks, verificationCheck };
+export type { VerificationCheck, VerificationStatus };

package/lib/release/channels.ts

@@ -0,0 +1,30 @@
+type FetchResponse = { ok: boolean; status: number; json(): Promise<unknown>; text(): Promise<string> };
+type Fetcher = (url: string) => Promise<FetchResponse>;
+
+async function inspectNpmChannel(name: string, version: string, fetcher: Fetcher = fetch as unknown as Fetcher) {
+  try {
+    const response = await fetcher(`https://registry.npmjs.org/${encodeURIComponent(name)}/${encodeURIComponent(version)}`);
+    if (response.status === 404) return { status: 'no-op' as const, published: false, version, error: null };
+    if (!response.ok) return { status: 'blocked' as const, published: null, version, error: { code: 'NPM_REGISTRY_UNAVAILABLE', message: `npm registry returned ${response.status}` } };
+    const body = await response.json() as Record<string, unknown>;
+    return { status: 'no-op' as const, published: body.version === version, version, error: null };
+  } catch (error) {
+    return { status: 'blocked' as const, published: null, version, error: { code: 'NPM_REGISTRY_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+async function inspectHomebrewChannel(url: string, version: string, fetcher: Fetcher = fetch as unknown as Fetcher) {
+  try {
+    const response = await fetcher(url);
+    if (response.status === 404) return { status: 'no-op' as const, published: false, version, error: null };
+    if (!response.ok) return { status: 'blocked' as const, 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' as const, published: new RegExp(`(?:version\\s+["']${escaped}["']|/v?${escaped}\\.)`).test(formula), version, error: null };
+  } catch (error) {
+    return { status: 'blocked' as const, published: null, version, error: { code: 'HOMEBREW_UNAVAILABLE', message: error instanceof Error ? error.message : String(error) } };
+  }
+}
+
+export { inspectHomebrewChannel, inspectNpmChannel };
+export type { Fetcher, FetchResponse };

package/lib/release/workflow.ts

@@ -0,0 +1,31 @@
+type ReleasePhase = 'unprepared' | 'prepared' | 'partially-published' | 'published' | 'post-pending' | 'complete';
+type ReleaseFacts = { localTag: boolean; localTagConflict?: boolean; remoteBranch: boolean; remoteTag: boolean; githubRelease: boolean | null; npm: boolean | null; homebrew: boolean | null; smoke: 'success' | 'pending' | 'failed' | null; postCommit: boolean };
+
+function deriveReleasePhase(facts: ReleaseFacts): ReleasePhase {
+  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: string, facts: ReleaseFacts) {
+  return { version, tag: `v${version.replace(/^v/, '')}`, phase: deriveReleasePhase(facts), facts };
+}
+
+async function runReleaseAction(input: { version: string; action: 'inspect' | 'prepare' | 'publish' | 'post'; inspect: () => Promise<ReleaseFacts>; prepare?: () => Promise<void>; publish?: () => Promise<void>; post?: () => Promise<void> }) {
+  const before = releaseSnapshot(input.version, await input.inspect());
+  if (input.action === 'inspect') return { status: 'no-op' as const, 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' as const : 'failed' as const, 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' as const : 'blocked' as const, 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 };
+export type { ReleaseFacts, ReleasePhase };

package/lib/render.ts

@@ -1,8 +1,9 @@
 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']);
 
 type Replacements = {

package/lib/run/index.ts

@@ -13,6 +13,7 @@ export type ParsedRunArgs = {
   taskRef: string | null;
   args: string[];
   tui: string | null;
+  recreate?: true;
 };
 
 export type SandboxRunRequest = {
@@ -20,6 +21,7 @@ export type SandboxRunRequest = {
   branch: string;
   command: string[];
   runId?: string;
+  recreate?: boolean;
 };
 
 export type SandboxRunResult = RunProcessResult & {
@@ -35,14 +37,15 @@ export type RunSkillOptions = {
   writeStderr?: (chunk: string) => void;
 };
 
-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: string[]): { rest: string[]; tui: string | null } {
   const rest: string[] = [];
@@ -65,17 +68,26 @@ export function parseRunArgs(args: string[]): ParsedRunArgs {
   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');
     return { skill, taskRef: null, args: createArgs, tui };
   }
   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 as const } : {})
+  };
 }
 
 function assertAllowedByConfig(skill: string, commandConfig: Record<string, unknown>): void {
@@ -129,7 +141,7 @@ function resolveActiveTaskIdentity(taskRef: string, repoRoot: string): ActiveTas
     const normalized = normalizeShortIdInput(taskRef, { shortIdLength: readShortIdLength(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;
@@ -207,7 +219,13 @@ export async function runSkill(args: string[], options: RunSkillOptions = {}): P
   const runSandbox =
     options.runSandbox ??
     ((request: SandboxRunRequest) => 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/lib/sandbox/capture.ts

@@ -3,6 +3,7 @@ import { loadConfig } from './config.ts';
 import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.ts';
 import { detectEngine } from './engine.ts';
 import { commandForEngine } from './shell.ts';
+import { ensureSandboxReady, type SandboxReadyResult } from './recovery.ts';
 import { hostTimezoneEnvFlags, terminalEnvFlags } from './commands/enter.ts';
 import {
   fetchSandboxRows,
@@ -16,6 +17,7 @@ export type SandboxCaptureRequest = {
   branch: string;
   command: string[];
   timeoutMs?: number;
+  recreate?: boolean;
 };
 
 export type SandboxCaptureResult = {
@@ -40,6 +42,11 @@ export type SandboxCaptureOptions = {
   containerCandidates?: string[];
   rows?: SandboxRow[];
   startContainer?: (name: string) => void;
+  ensureReady?: (params: {
+    branch: string;
+    row: SandboxRow;
+    allowRecreate: boolean;
+  }) => Promise<SandboxReadyResult>;
   spawn?: (file: string, args: string[]) => Promise<SandboxCaptureResult>;
 };
 
@@ -189,7 +196,26 @@ export async function runInSandbox(
       `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.ts');
+        await create([targetBranch, '--no-refresh']);
+      }
+    })).container;
+  } else if (!found.running) {
     (options.startContainer ?? ((name: string) => startSandboxContainer(engine, name)))(found.name);
   }
   const runId = options.runId ?? createRunId();
@@ -198,7 +224,7 @@ export async function runInSandbox(
     'exec',
     ...terminalEnvFlags(),
     ...hostTimezoneEnvFlags(),
-    found.name,
+    container,
     'bash',
     '-lc',
     buildTmuxLauncher({ request, runId })
@@ -210,7 +236,7 @@ export async function runInSandbox(
     run: {
       runId,
       engine,
-      container: found.name,
+      container,
       runDir
     }
   };

package/lib/sandbox/commands/create.ts

@@ -39,10 +39,18 @@ import {
 import { resolveTaskBranch } from '../task-resolver.ts';
 import {
   resolveTools,
+  tmpfsSeedStagingPath,
+  tmpfsSeedTargetPath,
   toolConfigDirCandidates
 } from '../tools.ts';
-import type { SandboxTool } from '../tools.ts';
+import type { SandboxTool, TmpfsSeedEntry } from '../tools.ts';
+import {
+  assertFreshSandboxReady,
+  hydrateTmpfsSeedEntries,
+  prepareTmpfsMounts
+} from '../recovery.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
+import { sandboxCoreBindMounts } from '../mounts.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
@@ -112,9 +120,7 @@ const HOST_PROXY_ENV_KEYS = [
 type SandboxCreateConfig = ReturnType<typeof loadConfig>;
 type PreparedDockerfile = ReturnType<typeof prepareDockerfile>;
 type ResolvedTool = { tool: SandboxTool; dir: string };
-type TmpfsSeedPlanEntry = {
-  stagingPath: string;
-  targetPath: string;
+type TmpfsSeedPlanEntry = TmpfsSeedEntry & {
   volumeArgs: string[];
 };
 type RuntimeCheck = { name: string; cmd: string[] };
@@ -1323,6 +1329,7 @@ export async function create(args: string[]): Promise<void> {
   const baseBranch = base ?? runSafe('git', ['-C', effectiveConfig.repoRoot, 'branch', '--show-current']);
   const expectedImageSignature = buildImageSignature(preparedDockerfile, tools);
   const engine = detectEngine(effectiveConfig);
+  let createdTmpfsSeedPlan: TmpfsSeedPlanEntry[] = [];
 
   p.intro(pc.cyan('AI Sandbox'));
   p.log.info(
@@ -1571,9 +1578,12 @@ export async function create(args: string[]): Promise<void> {
               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
@@ -1583,14 +1593,17 @@ export async function create(args: string[]): Promise<void> {
             // 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')]
                 }];
               })
@@ -1630,14 +1643,7 @@ export async function create(args: string[]): Promise<void> {
               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(
@@ -1650,25 +1656,30 @@ export async function create(args: string[]): Promise<void> {
               ...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
@@ -1737,6 +1748,13 @@ export async function create(args: string[]): Promise<void> {
   }
 
   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/lib/sandbox/commands/enter.ts

@@ -6,6 +6,7 @@ import {
   sandboxLabel
 } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
+import { ensureSandboxReady } from '../recovery.ts';
 import {
   formatCredentialWarnings,
   formatRemaining,
@@ -22,15 +23,15 @@ import {
   fetchSandboxRows,
   resolveBranchArg,
   selectSandboxContainer,
-  startSandboxContainer
 } from './list-running.ts';
 
-const USAGE = `Usage: ai sandbox exec <branch | TASK-id | N | '#N'> [cmd...]
+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)
@@ -123,6 +124,24 @@ export function formatCredentialSyncStatus(
   return null;
 }
 
+export function parseEnterArgs(args: string[]): {
+  target: string;
+  command: string[];
+  recreate: boolean;
+} {
+  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: string[]): Promise<number> {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(`${USAGE}\n`);
@@ -135,8 +154,8 @@ export async function enter(args: string[]): Promise<number> {
   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(
@@ -154,11 +173,19 @@ export async function enter(args: string[]): Promise<number> {
       `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.ts');
+      await create([targetBranch, '--no-refresh']);
+    }
+  });
+  const container = ready.container;
+  const cmd = parsed.command;
 
   if (config.tools.includes('claude-code')) {
     try {

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

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { runSafeEngine, runVerboseEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
+import { isRemovedHashShortIdInput } from '../../task/short-id.ts';
 
 export type SandboxRow = {
   name: string;
@@ -90,13 +91,13 @@ export function fetchSandboxRows(
 
 /**
  * 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: string): boolean {
-  return /^#?\d+$/.test(arg);
+  return /^\d+$/.test(arg);
 }
 
 type RegistryLookup =
@@ -115,9 +116,7 @@ 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.)
+  // 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' };
   const taskId = (result.stdout || '').trim();
@@ -149,7 +148,7 @@ function tryResolveFromRegistry(arg: string, repoRoot: string): RegistryLookup {
 
 /**
 /**
- * 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
@@ -169,13 +168,13 @@ export function resolveTaskShortRef(
   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
@@ -183,6 +182,9 @@ export function resolveTaskShortRef(
  * Callers still run assertValidBranchName on the result.
  */
 export function resolveBranchArg(arg: string, ctx: { repoRoot: string }): string {
+  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/lib/sandbox/commands/show.ts

@@ -7,12 +7,12 @@ import { assertValidBranchName, worktreeDirCandidates } from '../constants.ts';
 import { resolveBranchArg } from './list-running.ts';
 import { resolveTools, toolConfigDirCandidates } from '../tools.ts';
 
-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.`;
 
 export type SandboxDetail = {

package/lib/sandbox/commands/start.ts

@@ -6,33 +6,57 @@ import {
   sandboxLabel
 } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
+import { ensureSandboxReady } from '../recovery.ts';
 import {
   fetchSandboxRows,
   resolveBranchArg,
   selectSandboxContainer,
-  startSandboxContainer
 } from './list-running.ts';
 
-const USAGE = `Usage: ai sandbox start <branch | TASK-id | N | '#N'>
+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: string[]): { target: string; recreate: boolean; help: boolean } {
+  let recreate = false;
+  let help = false;
+  const positionals: string[] = [];
+  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: string[]): Promise<void> {
-  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(
@@ -51,11 +75,21 @@ export async function start(args: string[]): Promise<void> {
     );
   }
 
-  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.ts');
+      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`);
 }