@fitlab-ai/agent-infra 0.9.7 → 0.9.9

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

@@ -17,9 +17,11 @@ import { parseSandboxWorkspaceIdentity, resolveSandboxTarget, sameSandboxWorkspa
 import { createSandboxCapabilityPlan, runSandboxHooks, runBoundedSandboxHookCommand } from '../agent-client-reconciler.js';
 import { resolveTools, tmpfsSeedStagingPath, tmpfsSeedTargetPath, toolConfigDirCandidates } from '../tools.js';
 import { assertFreshSandboxReady, hydrateTmpfsSeedEntries, prepareTmpfsMounts, startSandboxControlBroker } from '../recovery.js';
+import { acquireSandboxControlReplacement, assertSandboxControlCutoverSnapshot, beginSandboxControlReplacement, captureSandboxControlCutoverSnapshot, commitSandboxControlReplacement, quiesceSandboxControlRoot, recoverSandboxControlReplacement, readSandboxControlManifestForTransition } from '../control/lifecycle.js';
+import { inspectSandboxControlContainer } from '../control/container-identity.js';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from '../mounts.js';
-import { assertSandboxTaskSource, finalizeSandboxControlManifest, materializeSandboxControl, materializeSandboxWorkspaceView, prepareSandboxWorkspaceMountTarget, } from '../workspace-view.js';
+import { assertSandboxTaskSource, finalizeSandboxControlManifest, materializeSandboxControl, materializeSandboxWorkspaceView, prepareSandboxWorkspaceMountTargets, sandboxControlPaths, } from '../workspace-view.js';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.js';
 import { validateSelinuxDisableEnv } from '../engines/selinux.js';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.js';
@@ -702,6 +704,12 @@ export async function create(args) {
     }
     const effectiveResolvedTools = resolvedTools;
     const container = containerName(effectiveConfig, branch);
+    const controlPaths = sandboxControlPaths({
+        base: effectiveConfig.controlBase,
+        project: effectiveConfig.project,
+        container,
+        identity: target.workspace
+    });
     const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
     const shareCommon = shareCommonDir(effectiveConfig);
     const shareBranch = shareBranchDir(effectiveConfig, branch);
@@ -863,344 +871,414 @@ export async function create(args) {
             {
                 title: `Starting container '${container}'`,
                 task: async (message) => {
-                    const existing = runSafeEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
-                    const matchedContainers = containerNameCandidates(effectiveConfig, branch)
-                        .filter((name) => existing.includes(name));
-                    if (matchedContainers.length > 0) {
-                        for (const name of matchedContainers) {
-                            const rawLabels = runSafeEngine(engine, 'docker', [
-                                'inspect', '--format', '{{json .Config.Labels}}', name
-                            ]).trim();
-                            let labels = {};
-                            try {
-                                labels = JSON.parse(rawLabels);
-                            }
-                            catch {
-                                labels = {};
+                    const hadControlRootBeforeAcquire = fs.existsSync(controlPaths.root);
+                    const replacementLease = acquireSandboxControlReplacement(controlPaths.root);
+                    let replacementLeaseHeld = true;
+                    let replacementCutover = null;
+                    try {
+                        const recoveryResult = await recoverSandboxControlReplacement(controlPaths.root, replacementLease);
+                        const hadExistingControlRoot = hadControlRootBeforeAcquire || recoveryResult === 'restored';
+                        const previousManifest = fs.existsSync(controlPaths.manifestPath)
+                            ? readSandboxControlManifestForTransition(controlPaths.manifestPath)
+                            : null;
+                        if (hadExistingControlRoot) {
+                            await quiesceSandboxControlRoot(controlPaths.root);
+                        }
+                        const previousCutoverSnapshot = hadExistingControlRoot
+                            ? captureSandboxControlCutoverSnapshot(controlPaths.root)
+                            : null;
+                        const existing = runSafeEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
+                        const matchedContainers = containerNameCandidates(effectiveConfig, branch)
+                            .filter((name) => existing.includes(name));
+                        if (matchedContainers.length > 0) {
+                            for (const name of matchedContainers) {
+                                const rawLabels = runSafeEngine(engine, 'docker', [
+                                    'inspect', '--format', '{{json .Config.Labels}}', name
+                                ]).trim();
+                                let labels = {};
+                                try {
+                                    labels = JSON.parse(rawLabels);
+                                }
+                                catch {
+                                    labels = {};
+                                }
+                                const existingIdentity = parseSandboxWorkspaceIdentity(labels, {
+                                    mode: sandboxWorkspaceModeLabel(effectiveConfig),
+                                    taskId: sandboxTaskIdLabel(effectiveConfig)
+                                });
+                                if (!sameSandboxWorkspaceIdentity(existingIdentity, target.workspace)) {
+                                    const existingDescription = existingIdentity.mode === 'task-bound'
+                                        ? `task-bound:${existingIdentity.taskId}`
+                                        : existingIdentity.mode;
+                                    const requestedDescription = target.workspace.mode === 'task-bound'
+                                        ? `task-bound:${target.workspace.taskId}`
+                                        : target.workspace.mode;
+                                    const recoveryTarget = target.workspace.mode === 'task-bound'
+                                        ? target.workspace.taskId
+                                        : branch;
+                                    throw new Error(`SANDBOX_WORKSPACE_IDENTITY_CONFLICT: container '${name}' is ${existingDescription}, `
+                                        + `but this request is ${requestedDescription}. `
+                                        + `Run 'ai sandbox start --recreate ${recoveryTarget}' on the host, then retry.`);
+                                }
                             }
-                            const existingIdentity = parseSandboxWorkspaceIdentity(labels, {
-                                mode: sandboxWorkspaceModeLabel(effectiveConfig),
-                                taskId: sandboxTaskIdLabel(effectiveConfig)
-                            });
-                            if (!sameSandboxWorkspaceIdentity(existingIdentity, target.workspace)) {
-                                const existingDescription = existingIdentity.mode === 'task-bound'
-                                    ? `task-bound:${existingIdentity.taskId}`
-                                    : existingIdentity.mode;
-                                const requestedDescription = target.workspace.mode === 'task-bound'
-                                    ? `task-bound:${target.workspace.taskId}`
-                                    : target.workspace.mode;
-                                const recoveryTarget = target.workspace.mode === 'task-bound'
-                                    ? target.workspace.taskId
-                                    : branch;
-                                throw new Error(`SANDBOX_WORKSPACE_IDENTITY_CONFLICT: container '${name}' is ${existingDescription}, `
-                                    + `but this request is ${requestedDescription}. `
-                                    + `Run 'ai sandbox start --recreate ${recoveryTarget}' on the host, then retry.`);
+                            message('Removing old container instance...');
+                            for (const name of matchedContainers) {
+                                runSafeEngine(engine, 'docker', ['stop', name]);
+                                runSafeEngine(engine, 'docker', ['rm', name]);
                             }
                         }
-                        message('Removing old container instance...');
-                        for (const name of matchedContainers) {
-                            runSafeEngine(engine, 'docker', ['stop', name]);
-                            runSafeEngine(engine, 'docker', ['rm', name]);
+                        if (previousManifest) {
+                            const oldContainer = await inspectSandboxControlContainer(previousManifest);
+                            if (oldContainer.state !== 'absent') {
+                                throw new Error(oldContainer.state === 'unknown'
+                                    ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${oldContainer.reason}`
+                                    : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
+                            }
                         }
-                    }
-                    const aliasesFile = ensureSandboxAliasesFile(effectiveConfig.home, capabilityPlan.aliases);
-                    if (aliasesFile.created) {
-                        message(`Created default sandbox aliases at ${aliasesFile.path}`);
-                    }
-                    const readmeResults = ensureSandboxDiscoveryReadmes(effectiveConfig, branch);
-                    for (const { created, path: readmePath } of readmeResults) {
-                        if (created) {
-                            message(`Created discovery README at ${readmePath}`);
+                        const aliasesFile = ensureSandboxAliasesFile(effectiveConfig.home, capabilityPlan.aliases);
+                        if (aliasesFile.created) {
+                            message(`Created default sandbox aliases at ${aliasesFile.path}`);
                         }
-                    }
-                    const gitconfigPath = path.join(effectiveConfig.home, '.gitconfig');
-                    const gitconfigContent = fs.existsSync(gitconfigPath)
-                        ? fs.readFileSync(gitconfigPath, 'utf8')
-                        : '';
-                    const needsGpg = detectGpgConfig(gitconfigContent);
-                    const hasHostGpgKeys = needsGpg && hostHasGpgKeys(effectiveConfig.home);
-                    const signingKey = needsGpg
-                        ? getGitSigningKey({ repoPath: worktree, home: effectiveConfig.home })
-                        : null;
-                    const cachedGpg = needsGpg
-                        ? readGpgCache(effectiveConfig.home, effectiveConfig.project, undefined, signingKey)
-                        : null;
-                    const proxyEntries = values['inherit-proxy'] ? collectHostProxyEntries(process.env) : [];
-                    const envFile = buildContainerEnvFile(effectiveResolvedTools, engine, undefined, {
-                        additionalEntries: proxyEntries
-                    });
-                    let hostShellConfig;
-                    let tmpfsSeedPlan = [];
-                    try {
-                        const beforeCreateResults = await runSandboxHooks({
-                            hooks: capabilityPlan.hooksByPhase['before-container-create'],
-                            phase: 'before-container-create',
-                            context: {
-                                config: effectiveConfig,
-                                plan: capabilityPlan,
-                                create: {
-                                    hostHome: effectiveConfig.home,
-                                    hostEnv: { ...process.env },
-                                    project: effectiveConfig.project,
-                                    resolvedTools: effectiveResolvedTools
-                                }
-                            },
-                            runCommand: runBoundedSandboxHookCommand
-                        });
-                        const beforeCreateFailure = beforeCreateResults.find((result) => result.status === 'fatal');
-                        if (beforeCreateFailure) {
-                            throw new Error(beforeCreateFailure.message
-                                ?? `Sandbox hook '${beforeCreateFailure.hookId}' failed.`);
+                        const readmeResults = ensureSandboxDiscoveryReadmes(effectiveConfig, branch);
+                        for (const { created, path: readmePath } of readmeResults) {
+                            if (created) {
+                                message(`Created discovery README at ${readmePath}`);
+                            }
                         }
-                        const toolVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => tool.tmpfs ? [] : ['-v', volumeArg(engine, dir, tool.containerMount)]);
-                        const tmpfsArgs = effectiveResolvedTools.flatMap(({ tool }) => tool.tmpfs ? buildTmpfsRunArgs(tool.containerMount, tool.tmpfs) : []);
-                        const workspaceView = materializeSandboxWorkspaceView({
-                            base: effectiveConfig.workspaceViewBase,
-                            project: effectiveConfig.project,
-                            container,
-                            identity: target.workspace
-                        });
-                        prepareSandboxWorkspaceMountTarget(worktree);
-                        const control = materializeSandboxControl({
-                            base: effectiveConfig.controlBase,
-                            repoRoot: effectiveConfig.repoRoot,
-                            worktreeRoot: worktree,
-                            project: effectiveConfig.project,
-                            container,
-                            branch,
-                            identity: target.workspace,
-                            engine
+                        const gitconfigPath = path.join(effectiveConfig.home, '.gitconfig');
+                        const gitconfigContent = fs.existsSync(gitconfigPath)
+                            ? fs.readFileSync(gitconfigPath, 'utf8')
+                            : '';
+                        const needsGpg = detectGpgConfig(gitconfigContent);
+                        const hasHostGpgKeys = needsGpg && hostHasGpgKeys(effectiveConfig.home);
+                        const signingKey = needsGpg
+                            ? getGitSigningKey({ repoPath: worktree, home: effectiveConfig.home })
+                            : null;
+                        const cachedGpg = needsGpg
+                            ? readGpgCache(effectiveConfig.home, effectiveConfig.project, undefined, signingKey)
+                            : null;
+                        const proxyEntries = values['inherit-proxy'] ? collectHostProxyEntries(process.env) : [];
+                        const envFile = buildContainerEnvFile(effectiveResolvedTools, engine, undefined, {
+                            additionalEntries: proxyEntries
                         });
-                        hostShellConfig = prepareHostShellConfig({
-                            home: effectiveConfig.home,
-                            project: effectiveConfig.project,
-                            branch,
-                            repoRoot: effectiveConfig.repoRoot
-                        });
-                        const coreVolumes = sandboxCoreBindMounts(effectiveConfig, branch, {
-                            worktree,
-                            shellConfigHostDir: hostShellConfig.hostDir,
-                            workspaceViewRoot: workspaceView.root,
-                            controlDir: control.channelDir,
-                            controlStatusDir: control.statusDir,
-                            ...(target.workspace.mode === 'task-bound'
-                                ? {
-                                    taskSource: assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId),
-                                    taskId: target.workspace.taskId
+                        let hostShellConfig;
+                        let tmpfsSeedPlan = [];
+                        try {
+                            const beforeCreateResults = await runSandboxHooks({
+                                hooks: capabilityPlan.hooksByPhase['before-container-create'],
+                                phase: 'before-container-create',
+                                context: {
+                                    config: effectiveConfig,
+                                    plan: capabilityPlan,
+                                    create: {
+                                        hostHome: effectiveConfig.home,
+                                        hostEnv: { ...process.env },
+                                        project: effectiveConfig.project,
+                                        resolvedTools: effectiveResolvedTools
+                                    }
+                                },
+                                runCommand: runBoundedSandboxHookCommand
+                            });
+                            const beforeCreateFailure = beforeCreateResults.find((result) => result.status === 'fatal');
+                            if (beforeCreateFailure) {
+                                throw new Error(beforeCreateFailure.message
+                                    ?? `Sandbox hook '${beforeCreateFailure.hookId}' failed.`);
+                            }
+                            const toolVolumes = effectiveResolvedTools.flatMap(({ tool, dir }) => tool.tmpfs ? [] : ['-v', volumeArg(engine, dir, tool.containerMount)]);
+                            const tmpfsArgs = effectiveResolvedTools.flatMap(({ tool }) => tool.tmpfs ? buildTmpfsRunArgs(tool.containerMount, tool.tmpfs) : []);
+                            const workspaceView = materializeSandboxWorkspaceView({
+                                base: effectiveConfig.workspaceViewBase,
+                                project: effectiveConfig.project,
+                                container,
+                                identity: target.workspace
+                            });
+                            prepareSandboxWorkspaceMountTargets(worktree);
+                            if (previousCutoverSnapshot) {
+                                assertSandboxControlCutoverSnapshot(previousCutoverSnapshot);
+                                if (previousManifest) {
+                                    const finalOldContainer = await inspectSandboxControlContainer(previousManifest);
+                                    if (finalOldContainer.state !== 'absent') {
+                                        throw new Error(finalOldContainer.state === 'unknown'
+                                            ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${finalOldContainer.reason}`
+                                            : 'SANDBOX_CONTROL_CONTAINER_REAPPEARED');
+                                    }
                                 }
-                                : {})
-                        }).flatMap(({ hostPaths, containerPath, readOnly }) => [
-                            '-v',
-                            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
-                        // user copies these entries into it so the runtime targets are normal,
-                        // writable files rather than nested mount points. The allowlist keeps
-                        // 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 [];
+                                replacementCutover = beginSandboxControlReplacement(controlPaths.root, replacementLease);
                             }
-                            const stagingPath = tmpfsSeedStagingPath(tool.id, index);
-                            return [{
-                                    toolId: tool.id,
-                                    containerMount: tool.containerMount,
-                                    stagingPath,
-                                    targetPath,
-                                    volumeArgs: ['-v', volumeArg(engine, hostPath, stagingPath, ':ro')]
-                                }];
-                        }));
-                        const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
-                            .filter(({ hostPath }) => fs.existsSync(hostPath))
-                            .flatMap(({ hostPath, containerSubpath }) => [
-                            '-v',
-                            volumeArg(engine, hostPath, path.posix.join(tool.containerMount, containerSubpath))
-                        ]));
-                        fs.mkdirSync(shareCommon, { recursive: true });
-                        fs.mkdirSync(shareBranch, { recursive: true });
-                        fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
-                        const dotfilesSnapshot = materializeDotfiles(effectiveConfig.dotfilesDir, dotfilesCacheDir(effectiveConfig.home, effectiveConfig.project));
-                        const dotfilesMount = dotfilesSnapshot
-                            ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
-                            : [];
-                        const hostTz = detectHostTimezone();
-                        const tzFlags = hostTz ? ['-e', `TZ=${hostTz}`] : [];
-                        let createdContainerRef = null;
-                        try {
-                            const dockerRunId = runEngineTaskCommand(engine, 'docker', [
-                                'run',
-                                '-d',
-                                '--init',
-                                '--name',
+                            const control = materializeSandboxControl({
+                                base: effectiveConfig.controlBase,
+                                repoRoot: effectiveConfig.repoRoot,
+                                worktreeRoot: worktree,
+                                project: effectiveConfig.project,
                                 container,
-                                '--hostname',
-                                `${effectiveConfig.project}-sandbox`,
-                                '--label',
-                                sandboxLabel(effectiveConfig),
-                                '--label',
-                                `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
-                                '--label',
-                                `${sandboxWorkspaceModeLabel(effectiveConfig)}=${target.workspace.mode}`,
+                                branch,
+                                identity: target.workspace,
+                                engine,
+                                replacementLease
+                            });
+                            hostShellConfig = prepareHostShellConfig({
+                                home: effectiveConfig.home,
+                                project: effectiveConfig.project,
+                                branch,
+                                repoRoot: effectiveConfig.repoRoot
+                            });
+                            const coreVolumes = sandboxCoreBindMounts(effectiveConfig, branch, {
+                                worktree,
+                                shellConfigHostDir: hostShellConfig.hostDir,
+                                workspaceViewRoot: workspaceView.root,
+                                controlDir: control.channelDir,
+                                controlStatusDir: control.statusDir,
+                                ...(target.workspace.mode === 'task-bound' ? { runtimeDir: control.runtimeDir } : {}),
                                 ...(target.workspace.mode === 'task-bound'
-                                    ? [
-                                        '--label',
-                                        `${sandboxTaskIdLabel(effectiveConfig)}=${target.workspace.taskId}`,
-                                        '-e',
-                                        `AGENT_INFRA_TASK_ID=${target.workspace.taskId}`
-                                    ]
-                                    : []),
-                                '-e',
-                                `AGENT_INFRA_CONTROL_TOKEN=${control.token}`,
-                                '-e',
-                                `AGENT_INFRA_CONTROL_GENERATION=${control.generation}`,
-                                '-e',
-                                'AGENT_INFRA_CONTROL_DIR=/run/agent-infra/control',
-                                '-e',
-                                'AGENT_INFRA_CONTROL_STATUS_DIR=/run/agent-infra/control-status',
-                                '--label',
-                                `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
-                                ...coreVolumes,
-                                ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
+                                    ? {
+                                        taskSource: assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId),
+                                        taskId: target.workspace.taskId
+                                    }
+                                    : {})
+                            }).flatMap(({ hostPaths, containerPath, readOnly }) => [
                                 '-v',
-                                volumeArg(engine, path.join(effectiveConfig.repoRoot, '.git'), `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`),
-                                ...dotfilesMount,
-                                ...toolVolumes,
-                                ...tmpfsArgs,
-                                ...tmpfsSeedPlan.flatMap(({ volumeArgs }) => volumeArgs),
-                                ...liveMountVolumes,
-                                ...envFile.dockerArgs,
-                                ...tzFlags,
-                                '-w',
-                                '/workspace',
-                                effectiveConfig.imageName
+                                volumeArg(engine, hostPaths[0], containerPath, readOnly ? ':ro' : '')
                             ]);
-                            createdContainerRef = dockerRunId.trim();
-                            const containerId = runEngineTaskCommand(engine, 'docker', [
-                                'inspect', '--format', '{{.Id}}', dockerRunId.trim()
-                            ]).trim();
-                            if (!containerId)
-                                throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
-                            const rawContainerLabels = runEngineTaskCommand(engine, 'docker', [
-                                'inspect', '--format', '{{json .Config.Labels}}', containerId
-                            ]).trim();
-                            let inspectedLabels;
+                            // Mount each declared seed read-only at an isolated staging path.
+                            // After docker run mounts the empty tmpfs, the container's default
+                            // user copies these entries into it so the runtime targets are normal,
+                            // writable files rather than nested mount points. The allowlist keeps
+                            // 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 = tmpfsSeedStagingPath(tool.id, index);
+                                return [{
+                                        toolId: tool.id,
+                                        containerMount: tool.containerMount,
+                                        stagingPath,
+                                        targetPath,
+                                        volumeArgs: ['-v', volumeArg(engine, hostPath, stagingPath, ':ro')]
+                                    }];
+                            }));
+                            const liveMountVolumes = effectiveResolvedTools.flatMap(({ tool }) => (tool.hostLiveMounts ?? [])
+                                .filter(({ hostPath }) => fs.existsSync(hostPath))
+                                .flatMap(({ hostPath, containerSubpath }) => [
+                                '-v',
+                                volumeArg(engine, hostPath, path.posix.join(tool.containerMount, containerSubpath))
+                            ]));
+                            fs.mkdirSync(shareCommon, { recursive: true });
+                            fs.mkdirSync(shareBranch, { recursive: true });
+                            fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
+                            const dotfilesSnapshot = materializeDotfiles(effectiveConfig.dotfilesDir, dotfilesCacheDir(effectiveConfig.home, effectiveConfig.project));
+                            const dotfilesMount = dotfilesSnapshot
+                                ? buildDotfilesVolumeArgs(engine, dotfilesSnapshot.cacheDir)
+                                : [];
+                            const hostTz = detectHostTimezone();
+                            const tzFlags = hostTz ? ['-e', `TZ=${hostTz}`] : [];
+                            let createdContainerRef = null;
                             try {
-                                inspectedLabels = JSON.parse(rawContainerLabels);
-                            }
-                            catch {
-                                throw new Error('SANDBOX_CONTROL_CONTAINER_LABELS_INVALID');
-                            }
-                            if (!inspectedLabels || typeof inspectedLabels !== 'object' || Array.isArray(inspectedLabels)) {
-                                throw new Error('SANDBOX_CONTROL_CONTAINER_LABELS_INVALID');
+                                const dockerRunId = runEngineTaskCommand(engine, 'docker', [
+                                    'run',
+                                    '-d',
+                                    '--init',
+                                    '--name',
+                                    container,
+                                    '--hostname',
+                                    `${effectiveConfig.project}-sandbox`,
+                                    '--label',
+                                    sandboxLabel(effectiveConfig),
+                                    '--label',
+                                    `${sandboxBranchLabel(effectiveConfig)}=${branch}`,
+                                    '--label',
+                                    `${sandboxWorkspaceModeLabel(effectiveConfig)}=${target.workspace.mode}`,
+                                    ...(target.workspace.mode === 'task-bound'
+                                        ? [
+                                            '--label',
+                                            `${sandboxTaskIdLabel(effectiveConfig)}=${target.workspace.taskId}`,
+                                            '-e',
+                                            `AGENT_INFRA_TASK_ID=${target.workspace.taskId}`
+                                        ]
+                                        : []),
+                                    '-e',
+                                    `AGENT_INFRA_CONTROL_TOKEN=${control.token}`,
+                                    '-e',
+                                    `AGENT_INFRA_CONTROL_GENERATION=${control.generation}`,
+                                    '-e',
+                                    'AGENT_INFRA_CONTROL_DIR=/run/agent-infra/control',
+                                    '-e',
+                                    'AGENT_INFRA_CONTROL_STATUS_DIR=/run/agent-infra/control-status',
+                                    ...(target.workspace.mode === 'task-bound'
+                                        ? ['-e', 'AGENT_INFRA_RUNTIME_DIR=/run/agent-infra/runtime']
+                                        : []),
+                                    '--label',
+                                    `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
+                                    ...coreVolumes,
+                                    ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
+                                    '-v',
+                                    volumeArg(engine, path.join(effectiveConfig.repoRoot, '.git'), `${toEnginePath(engine, effectiveConfig.repoRoot)}/.git`),
+                                    ...dotfilesMount,
+                                    ...toolVolumes,
+                                    ...tmpfsArgs,
+                                    ...tmpfsSeedPlan.flatMap(({ volumeArgs }) => volumeArgs),
+                                    ...liveMountVolumes,
+                                    ...envFile.dockerArgs,
+                                    ...tzFlags,
+                                    '-w',
+                                    '/workspace',
+                                    effectiveConfig.imageName
+                                ]);
+                                createdContainerRef = dockerRunId.trim();
+                                const containerId = runEngineTaskCommand(engine, 'docker', [
+                                    'inspect', '--format', '{{.Id}}', dockerRunId.trim()
+                                ]).trim();
+                                if (!containerId)
+                                    throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
+                                const rawContainerLabels = runEngineTaskCommand(engine, 'docker', [
+                                    'inspect', '--format', '{{json .Config.Labels}}', containerId
+                                ]).trim();
+                                let inspectedLabels;
+                                try {
+                                    inspectedLabels = JSON.parse(rawContainerLabels);
+                                }
+                                catch {
+                                    throw new Error('SANDBOX_CONTROL_CONTAINER_LABELS_INVALID');
+                                }
+                                if (!inspectedLabels || typeof inspectedLabels !== 'object' || Array.isArray(inspectedLabels)) {
+                                    throw new Error('SANDBOX_CONTROL_CONTAINER_LABELS_INVALID');
+                                }
+                                const expectedLabels = {
+                                    [sandboxLabel(effectiveConfig)]: '',
+                                    [sandboxBranchLabel(effectiveConfig)]: branch,
+                                    [sandboxWorkspaceModeLabel(effectiveConfig)]: target.workspace.mode,
+                                    [sandboxRuntimeCapabilityLabel(effectiveConfig)]: capabilityPlan.runtimeSignature,
+                                    ...(target.workspace.mode === 'task-bound'
+                                        ? { [sandboxTaskIdLabel(effectiveConfig)]: target.workspace.taskId }
+                                        : {})
+                                };
+                                const labels = inspectedLabels;
+                                for (const [key, expected] of Object.entries(expectedLabels)) {
+                                    if (labels[key] !== expected)
+                                        throw new Error('SANDBOX_CONTROL_CONTAINER_IDENTITY_MISMATCH');
+                                }
+                                finalizeSandboxControlManifest(control, {
+                                    engine,
+                                    id: containerId,
+                                    labels: expectedLabels
+                                });
+                                replacementLease.clearQuiescing();
+                                await startSandboxControlBroker(effectiveConfig.repoRoot, control.manifestPath);
+                                if (replacementCutover) {
+                                    commitSandboxControlReplacement(control.root, replacementLease);
+                                    replacementCutover = null;
+                                }
+                                createdTmpfsSeedPlan = tmpfsSeedPlan;
                             }
-                            const expectedLabels = {
-                                [sandboxLabel(effectiveConfig)]: '',
-                                [sandboxBranchLabel(effectiveConfig)]: branch,
-                                [sandboxWorkspaceModeLabel(effectiveConfig)]: target.workspace.mode,
-                                [sandboxRuntimeCapabilityLabel(effectiveConfig)]: capabilityPlan.runtimeSignature,
-                                ...(target.workspace.mode === 'task-bound'
-                                    ? { [sandboxTaskIdLabel(effectiveConfig)]: target.workspace.taskId }
-                                    : {})
-                            };
-                            const labels = inspectedLabels;
-                            for (const [key, expected] of Object.entries(expectedLabels)) {
-                                if (labels[key] !== expected)
-                                    throw new Error('SANDBOX_CONTROL_CONTAINER_IDENTITY_MISMATCH');
+                            catch (error) {
+                                if (createdContainerRef) {
+                                    runSafeEngine(engine, 'docker', ['stop', createdContainerRef]);
+                                    runSafeEngine(engine, 'docker', ['rm', createdContainerRef]);
+                                }
+                                if (!hadExistingControlRoot)
+                                    removeDirRecursive(control.root);
+                                if (replacementCutover) {
+                                    try {
+                                        await recoverSandboxControlReplacement(control.root, replacementLease);
+                                        replacementCutover = null;
+                                    }
+                                    catch {
+                                        // Preserve the cutover state for the next explicit recreate to recover.
+                                    }
+                                }
+                                removeDirRecursive(workspaceView.root);
+                                throw error;
                             }
-                            finalizeSandboxControlManifest(control, {
-                                engine,
-                                id: containerId,
-                                labels: expectedLabels
-                            });
-                            await startSandboxControlBroker(effectiveConfig.repoRoot, control.manifestPath);
-                            createdTmpfsSeedPlan = tmpfsSeedPlan;
                         }
-                        catch (error) {
-                            if (createdContainerRef) {
-                                runSafeEngine(engine, 'docker', ['stop', createdContainerRef]);
-                                runSafeEngine(engine, 'docker', ['rm', createdContainerRef]);
-                            }
-                            removeDirRecursive(control.root);
-                            removeDirRecursive(workspaceView.root);
-                            throw error;
+                        finally {
+                            envFile.cleanup();
                         }
-                    }
-                    finally {
-                        envFile.cleanup();
-                    }
-                    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
-                    // ~/.gitconfig and friends pointing into the host bind-mount.
-                    // `ln -sf` is idempotent for the default image.
-                    ensureShellConfigSymlinks(engine, container);
-                    if (needsGpg) {
-                        message(cachedGpg
-                            ? 'Syncing GPG keys from cache...'
-                            : hasHostGpgKeys
-                                ? 'Syncing GPG keys (you may be prompted for your passphrase)...'
-                                : 'Checking GPG cache before falling back to stripped git config...');
-                        try {
-                            if (syncGpgKeys(container, effectiveConfig.home, effectiveConfig.project, undefined, undefined, {
-                                cachedOverride: cachedGpg,
-                                repoPath: worktree,
-                                signingKey,
-                                dockerExecFn: (cmd, args, opts) => execEngine(engine, cmd, args, opts),
-                                dockerRunSafeFn: (cmd, args, opts) => runSafeEngine(engine, cmd, args, opts)
-                            })) {
-                                writeSanitizedGitconfig({
-                                    home: effectiveConfig.home,
-                                    hostConfigDir: hostShellConfig.hostDir,
-                                    stripGpg: false,
-                                    repoRoot: effectiveConfig.repoRoot
-                                });
+                        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
+                        // ~/.gitconfig and friends pointing into the host bind-mount.
+                        // `ln -sf` is idempotent for the default image.
+                        ensureShellConfigSymlinks(engine, container);
+                        if (needsGpg) {
+                            message(cachedGpg
+                                ? 'Syncing GPG keys from cache...'
+                                : hasHostGpgKeys
+                                    ? 'Syncing GPG keys (you may be prompted for your passphrase)...'
+                                    : 'Checking GPG cache before falling back to stripped git config...');
+                            try {
+                                if (syncGpgKeys(container, effectiveConfig.home, effectiveConfig.project, undefined, undefined, {
+                                    cachedOverride: cachedGpg,
+                                    repoPath: worktree,
+                                    signingKey,
+                                    dockerExecFn: (cmd, args, opts) => execEngine(engine, cmd, args, opts),
+                                    dockerRunSafeFn: (cmd, args, opts) => runSafeEngine(engine, cmd, args, opts)
+                                })) {
+                                    writeSanitizedGitconfig({
+                                        home: effectiveConfig.home,
+                                        hostConfigDir: hostShellConfig.hostDir,
+                                        stripGpg: false,
+                                        repoRoot: effectiveConfig.repoRoot
+                                    });
+                                }
+                                else {
+                                    message(hasHostGpgKeys
+                                        ? 'GPG key sync failed; using stripped git config fallback...'
+                                        : 'Host GPG keys unavailable; using stripped git config fallback...');
+                                }
                             }
-                            else {
+                            catch {
                                 message(hasHostGpgKeys
                                     ? 'GPG key sync failed; using stripped git config fallback...'
                                     : 'Host GPG keys unavailable; using stripped git config fallback...');
                             }
                         }
-                        catch {
-                            message(hasHostGpgKeys
-                                ? 'GPG key sync failed; using stripped git config fallback...'
-                                : 'Host GPG keys unavailable; using stripped git config fallback...');
+                        for (const { tool } of effectiveResolvedTools) {
+                            for (const command of tool.postSetupCmds ?? []) {
+                                runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
+                            }
                         }
-                    }
-                    for (const { tool } of effectiveResolvedTools) {
-                        for (const command of tool.postSetupCmds ?? []) {
-                            runSafeEngine(engine, 'docker', ['exec', container, 'bash', '-lc', command]);
+                        const afterStartResults = await runSandboxHooks({
+                            hooks: capabilityPlan.hooksByPhase['after-container-start'],
+                            phase: 'after-container-start',
+                            context: { config: effectiveConfig, plan: capabilityPlan },
+                            runCommand: runBoundedSandboxHookCommand
+                        });
+                        const afterStartFailure = afterStartResults.find((result) => result.status === 'fatal');
+                        if (afterStartFailure) {
+                            throw new Error(afterStartFailure.message
+                                ?? `Sandbox hook '${afterStartFailure.hookId}' failed.`);
                         }
+                        replacementLease.release();
+                        replacementLeaseHeld = false;
+                        return 'Container started';
                     }
-                    const afterStartResults = await runSandboxHooks({
-                        hooks: capabilityPlan.hooksByPhase['after-container-start'],
-                        phase: 'after-container-start',
-                        context: { config: effectiveConfig, plan: capabilityPlan },
-                        runCommand: runBoundedSandboxHookCommand
-                    });
-                    const afterStartFailure = afterStartResults.find((result) => result.status === 'fatal');
-                    if (afterStartFailure) {
-                        throw new Error(afterStartFailure.message
-                            ?? `Sandbox hook '${afterStartFailure.hookId}' failed.`);
+                    catch (error) {
+                        if (replacementLeaseHeld) {
+                            try {
+                                replacementLease.release();
+                            }
+                            catch {
+                                // Preserve the original cutover failure and its evidence.
+                            }
+                        }
+                        throw error;
                     }
-                    return 'Container started';
                 }
             }
         ]);