@fitlab-ai/agent-infra 0.8.5 → 0.9.1

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/build-proxy.js

@@ -0,0 +1,63 @@
+import semver from 'semver';
+import { engineDisplayName } from './engine.js';
+import { runSafeEngine } from './shell.js';
+export const BUILD_PROXY_ENV_KEYS = ['HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY'];
+export const MIN_BUILD_PROXY_DOCKER_VERSION = '20.10.0';
+export const MIN_BUILD_PROXY_BUILDKIT_VERSION = '0.9.0';
+export function prepareBuildProxy(enabled, hostEnv, engine) {
+    const env = { ...hostEnv };
+    if (!enabled) {
+        return { args: [], env, redactionValues: [] };
+    }
+    const entries = BUILD_PROXY_ENV_KEYS.flatMap((key) => {
+        const value = hostEnv[key]?.trim();
+        return value ? [[key, value]] : [];
+    });
+    if (entries.length === 0) {
+        throw new Error(`No non-empty build proxy variables are set. Configure one of: ${BUILD_PROXY_ENV_KEYS.join(', ')}.`);
+    }
+    for (const [key, value] of entries)
+        env[key] = value;
+    if (engine === 'wsl2') {
+        const existing = (env.WSLENV ?? '').split(':').filter(Boolean);
+        env.WSLENV = [...new Set([...existing, ...entries.map(([key]) => key)])].join(':');
+    }
+    return {
+        args: entries.flatMap(([key]) => ['--secret', `id=${key},env=${key}`]),
+        env,
+        redactionValues: entries.map(([, value]) => value)
+    };
+}
+function parsedVersion(raw) {
+    return semver.coerce(raw.trim())?.version ?? null;
+}
+export function assertBuildProxyCompatibility(engine, runSafeEngineFn = runSafeEngine) {
+    const dockerRaw = runSafeEngineFn(engine, 'docker', ['version', '--format', '{{.Server.Version}}']);
+    const dockerVersion = parsedVersion(dockerRaw);
+    if (!dockerVersion || !semver.gte(dockerVersion, MIN_BUILD_PROXY_DOCKER_VERSION)) {
+        throw new Error(`Build proxy requires Docker Engine ${MIN_BUILD_PROXY_DOCKER_VERSION} or newer; `
+            + `observed ${dockerVersion ?? 'an unparseable version'}.`);
+    }
+    const buildxRaw = runSafeEngineFn(engine, 'docker', ['buildx', 'inspect', '--bootstrap']);
+    const versions = [...buildxRaw.matchAll(/BuildKit(?:\s+version)?:\s*v?(\d+\.\d+\.\d+(?:[-+][^\s]+)?)/gi)]
+        .map((match) => parsedVersion(match[1] ?? ''))
+        .filter((version) => version !== null);
+    if (versions.length === 0) {
+        throw new Error(`Build proxy requires BuildKit ${MIN_BUILD_PROXY_BUILDKIT_VERSION} or newer, `
+            + 'but the active builder version could not be determined.');
+    }
+    const oldVersion = versions.find((version) => !semver.gte(version, MIN_BUILD_PROXY_BUILDKIT_VERSION));
+    if (oldVersion) {
+        throw new Error(`Build proxy observed BuildKit ${oldVersion}; version ${MIN_BUILD_PROXY_BUILDKIT_VERSION} or newer is required.`);
+    }
+}
+export function redactBuildProxyValues(text, values) {
+    return [...new Set(values.filter(Boolean))]
+        .sort((left, right) => right.length - left.length)
+        .reduce((result, value) => result.replaceAll(value, '[REDACTED_BUILD_PROXY]'), text);
+}
+export function buildProxyFailureHint(engine) {
+    return `Build-step proxy inheritance is enabled for ${engineDisplayName(engine)}. `
+        + 'Image pulls and Dockerfile FROM resolution use the Docker daemon or builder proxy configuration.';
+}
+//# sourceMappingURL=build-proxy.js.map

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

@@ -10,11 +10,14 @@ import * as toml from 'smol-toml';
 import { loadConfig } from '../config.js';
 import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxImageRefreshLabel, sandboxLabel, shareBranchDir, shareCommonDir, shellConfigDir, worktreeDirCandidates } from '../constants.js';
 import { prepareDockerfile } from '../dockerfile.js';
+import { assertBuildProxyCompatibility, buildProxyFailureHint, prepareBuildProxy, redactBuildProxyValues } from '../build-proxy.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';
@@ -47,7 +50,7 @@ alias gy='gemini --yolo; tput ed'
 `;
 const CONTAINER_HOME = '/home/devuser';
 const CONTAINER_SHELL_CONFIG_MOUNT = `${CONTAINER_HOME}/.host-shell-config`;
-const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh] [--inherit-proxy|-P]
+const USAGE = `Usage: ai sandbox create <branch> [base] [--cpu <n>] [--memory <n>] [--no-refresh] [--inherit-proxy|-P] [--inherit-build-proxy|-B]
 
 Host aliases:
   ${'~'}/.agent-infra/aliases/sandbox.sh is auto-created on first run and exposed
@@ -57,7 +60,9 @@ Host aliases:
 
 Proxy:
   --inherit-proxy, -P  Copy non-empty standard host proxy variables into the
-                       container environment through the private env file.`;
+                       container environment through the private env file.
+  --inherit-build-proxy, -B  Pass uppercase HTTP_PROXY, HTTPS_PROXY, and NO_PROXY
+                             to managed image build steps for this invocation.`;
 const HOST_PROXY_ENV_KEYS = [
     'http_proxy',
     'HTTP_PROXY',
@@ -68,6 +73,15 @@ const HOST_PROXY_ENV_KEYS = [
     'no_proxy',
     'NO_PROXY'
 ];
+const MANAGED_GITHUB_GIT_CONFIG = [
+    '[credential]',
+    '\thelper = !gh auth git-credential',
+    '[credential "https://github.com"]',
+    '\thelper =',
+    '\thelper = !gh auth git-credential',
+    '[url "https://github.com/"]',
+    '\tinsteadOf = git@github.com:'
+];
 function resolveToolDirs(config, tools, branch) {
     return tools.map((tool) => {
         const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -156,6 +170,14 @@ function normalizeContainerHomeSeparators(content) {
     const containerHomePattern = new RegExp(`${escapeRegExp(CONTAINER_HOME)}\\S*`, 'g');
     return content.replace(containerHomePattern, (value) => value.replaceAll('\\', '/'));
 }
+function isGitHubCliCredentialHelper(line) {
+    const helperMatch = line.match(/^\s*helper\s*=\s*(.+?)\s*$/i);
+    if (!helperMatch) {
+        return false;
+    }
+    const helper = (helperMatch[1] ?? '').trim().replace(/^"(.*)"$/, '$1');
+    return /^!\s*(?:"[^"]*[\\/]+gh"|(?:\S*[\\/]+)?gh)\s+auth\s+git-credential(?:\s|$)/i.test(helper);
+}
 export function sanitizeGitConfig(gitconfig, home, { stripGpg = false, repoRoot = '' } = {}) {
     const posixHome = home.replaceAll('\\', '/');
     const normalizedGitconfig = gitconfig
@@ -168,10 +190,12 @@ export function sanitizeGitConfig(gitconfig, home, { stripGpg = false, repoRoot
     const sanitized = [];
     let inGpgSection = false;
     let currentSection = '';
+    let currentSectionName = '';
     for (const line of lines) {
         const sectionMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
         if (sectionMatch) {
             const sectionName = (sectionMatch[1] ?? '').trim();
+            currentSectionName = sectionName;
             currentSection = ((sectionName.match(/^([^\s"]+)/)?.[1]) ?? '').toLowerCase();
             inGpgSection = /^gpg(?:\s+"[^"]+")?$/i.test(sectionName);
             if (stripGpg && inGpgSection) {
@@ -197,9 +221,19 @@ export function sanitizeGitConfig(gitconfig, home, { stripGpg = false, repoRoot
         if (stripGpg && currentSection === 'user' && /^\s*signingKey\s*=.*$/i.test(line)) {
             continue;
         }
+        if (currentSection === 'credential' && isGitHubCliCredentialHelper(line)) {
+            continue;
+        }
+        if (/^url\s+"https:\/\/github\.com\/"$/i.test(currentSectionName)
+            && /^\s*insteadOf\s*=\s*git@github\.com:\s*$/i.test(line)) {
+            continue;
+        }
         sanitized.push(line);
     }
-    return appendSafeDirectories(sanitized, repoRoot).join('\n');
+    return [
+        ...appendSafeDirectories(sanitized, repoRoot),
+        ...MANAGED_GITHUB_GIT_CONFIG
+    ].join('\n');
 }
 export function hostHasGpgKeys(home, execFn = execFileSync) {
     return currentKeyringFingerprint(home, execFn) !== null;
@@ -926,7 +960,7 @@ export function buildTmpfsRunArgs(containerMount, tmpfs) {
     const size = tmpfs.size ?? '512m';
     return ['--tmpfs', `${containerMount}:rw,size=${size}`];
 }
-export function buildImage(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, runVerboseFn = runVerboseEngine, env = process.env, refresh = false, lastRefresh } = {}) {
+export function buildImage(config, tools, dockerfilePath, imageSignature, { engine, runFn = runEngine, runSafeFn = runSafeEngine, runVerboseFn = runVerboseEngine, env = process.env, refresh = false, lastRefresh, buildProxyArgs = [], buildEnv } = {}) {
     const selectedEngine = engine ?? detectEngine({ engine: config.engine });
     runVerboseFn(selectedEngine, 'docker', buildSandboxImageArgs(config, tools, dockerfilePath, imageSignature, {
         engine: selectedEngine,
@@ -934,8 +968,9 @@ export function buildImage(config, tools, dockerfilePath, imageSignature, { engi
         runSafeFn,
         env,
         refresh,
-        lastRefresh
-    }), { cwd: config.repoRoot });
+        lastRefresh,
+        buildProxyArgs
+    }), { cwd: config.repoRoot, env: buildEnv });
 }
 function readImageLabels(config, engine) {
     return parseImageLabels(runSafeEngine(engine, 'docker', [
@@ -956,6 +991,7 @@ export async function create(args) {
             memory: { type: 'string' },
             'no-refresh': { type: 'boolean' },
             'inherit-proxy': { type: 'boolean', short: 'P' },
+            'inherit-build-proxy': { type: 'boolean', short: 'B' },
             help: { type: 'boolean', short: 'h' }
         }
     });
@@ -999,6 +1035,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') {
@@ -1024,6 +1061,12 @@ export async function create(args) {
             && isRefreshDue(currentLastRefresh, now, effectiveConfig.refreshIntervalDays);
         const needsImageBuild = signatureStale || refreshDue;
         if (needsImageBuild) {
+            if (values['inherit-build-proxy'] && effectiveConfig.dockerfile) {
+                throw new Error('Build proxy inheritance is unavailable with a custom sandbox Dockerfile.');
+            }
+            const buildProxy = prepareBuildProxy(values['inherit-build-proxy'] ?? false, process.env, engine);
+            if (values['inherit-build-proxy'])
+                assertBuildProxyCompatibility(engine);
             const buildRefresh = !imageExists || refreshDue;
             const buildLastRefresh = buildRefresh ? now : currentLastRefresh || 0;
             p.log.step(refreshDue
@@ -1032,7 +1075,13 @@ export async function create(args) {
                     ? 'Rebuilding stale image...'
                     : 'Building image for first use...');
             try {
-                buildImage(effectiveConfig, tools, preparedDockerfile.path, expectedImageSignature, { engine, refresh: buildRefresh, lastRefresh: buildLastRefresh });
+                buildImage(effectiveConfig, tools, preparedDockerfile.path, expectedImageSignature, {
+                    engine,
+                    refresh: buildRefresh,
+                    lastRefresh: buildLastRefresh,
+                    buildProxyArgs: buildProxy.args,
+                    buildEnv: buildProxy.env
+                });
                 p.log.success(refreshDue
                     ? 'Image refreshed'
                     : imageExists
@@ -1042,10 +1091,12 @@ export async function create(args) {
             catch (error) {
                 if (refreshDue && !signatureStale && imageExists) {
                     p.log.warn('Scheduled sandbox image refresh failed; continuing with the existing image. ' +
-                        commandErrorMessage(error));
+                        redactBuildProxyValues(commandErrorMessage(error), buildProxy.redactionValues)
+                        + (values['inherit-build-proxy'] ? ` ${buildProxyFailureHint(engine)}` : ''));
                 }
                 else {
-                    throw error;
+                    const hint = values['inherit-build-proxy'] ? `\n${buildProxyFailureHint(engine)}` : '';
+                    throw new Error(`${redactBuildProxyValues(commandErrorMessage(error), buildProxy.redactionValues)}${hint}`);
                 }
             }
         }
@@ -1209,9 +1260,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 +1274,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 +1315,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 +1324,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 +1401,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.