@fitlab-ai/agent-infra 0.9.3 → 0.9.4

package/dist/lib/run/tui.js

@@ -1,6 +1,12 @@
 import { renderAgentClientInvocation } from '../agent-clients/invocation.js';
 import { getAgentClientAdapter } from '../agent-clients/registry.js';
 const TUI_NAMES = new Set(['claude', 'codex', 'antigravity', 'opencode']);
+const TUI_AGENT_CLIENT_IDS = Object.freeze({
+    claude: 'claude-code',
+    codex: 'codex',
+    antigravity: 'antigravity-cli',
+    opencode: 'opencode'
+});
 function isTuiName(value) {
     return typeof value === 'string' && TUI_NAMES.has(value);
 }
@@ -18,14 +24,7 @@ export function selectTui(skill, options) {
     return 'codex';
 }
 export function renderPrompt(params) {
-    const suffix = [params.skill, ...params.args].join(' ').trim();
-    if (params.tui === 'codex') {
-        return renderAgentClientInvocation(getAgentClientAdapter('codex').invocation, {
-            skillName: params.skill,
-            args: params.args
-        });
-    }
-    return `/${suffix}`;
+    return renderAgentClientInvocation(getAgentClientAdapter(TUI_AGENT_CLIENT_IDS[params.tui]).invocation, { skillName: params.skill, args: params.args });
 }
 export function buildTuiCommand(tui, prompt) {
     if (tui === 'claude')

package/dist/lib/sandbox/agent-client-reconciler.js

@@ -62,6 +62,27 @@ function assertUniqueTools(tools) {
         seen.add(tool.id);
     }
 }
+function unique(values) {
+    return Object.freeze([...new Set(values)]);
+}
+function sandboxImageContribution(adapters, tools) {
+    const homePrefix = '/home/devuser/';
+    const derivedExclusions = tools.map((tool) => {
+        if (!tool.containerMount.startsWith(homePrefix)) {
+            throw new Error(`Agent Client '${tool.id}' container mount must be below ${homePrefix.slice(0, -1)}`);
+        }
+        return tool.containerMount.slice(homePrefix.length);
+    });
+    return Object.freeze({
+        dockerfileFragments: unique(adapters.flatMap((adapter) => adapter.sandbox.image?.dockerfileFragment
+            ? [adapter.sandbox.image.dockerfileFragment]
+            : [])),
+        dotfilesExclusions: unique([
+            ...derivedExclusions,
+            ...adapters.flatMap((adapter) => adapter.sandbox.image?.dotfilesExclusions ?? [])
+        ])
+    });
+}
 function hooksByPhase(adapters) {
     const phases = [
         'prepare',
@@ -108,6 +129,7 @@ function createSandboxCapabilityPlan(config) {
     }
     const tools = Object.freeze([...nonClientTools, ...selectedTools, ...selectedCustomTools]);
     assertUniqueTools(tools);
+    const image = sandboxImageContribution(selectedAgentClients, selectedTools);
     const phaseHooks = hooksByPhase(selectedAgentClients);
     const hookProjection = selectedAgentClients.flatMap((adapter) => adapter.sandbox.hooks.map((hook) => ({
         adapterId: adapter.id,
@@ -134,7 +156,8 @@ function createSandboxCapabilityPlan(config) {
         tools: Object.freeze(tools.map(runtimeToolProjection)),
         selectedAgentClients: Object.freeze(selectedAgentClients.map((adapter) => adapter.id)),
         hooks: Object.freeze(hookProjection),
-        recoveryChecks: recoveryCheckProjection
+        recoveryChecks: recoveryCheckProjection,
+        image
     });
     const cleanupInventory = Object.freeze([
         agentInfraTool(config.home),
@@ -148,6 +171,7 @@ function createSandboxCapabilityPlan(config) {
         hooksByPhase: phaseHooks,
         recoveryChecks,
         aliases: Object.freeze(listAgentClientAdapters().flatMap((adapter) => adapter.sandbox.aliases)),
+        image,
         imageSignature: hash(tools.map(({ id, install }) => ({ id, install }))),
         runtimeSignature: hash(runtimeProjection),
         runtimeProjection,
@@ -230,5 +254,5 @@ function runBoundedSandboxHookCommand(command, options) {
         });
     });
 }
-export { DEFAULT_SANDBOX_HOOK_TIMEOUT_MS, createSandboxCapabilityPlan, runBoundedSandboxHookCommand, runSandboxHooks };
+export { DEFAULT_SANDBOX_HOOK_TIMEOUT_MS, createSandboxCapabilityPlan, runBoundedSandboxHookCommand, runSandboxHooks, sandboxImageContribution };
 //# sourceMappingURL=agent-client-reconciler.js.map

package/dist/lib/sandbox/capture.js

@@ -6,6 +6,7 @@ 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';
+import { resolveSandboxTarget } from './workspace-identity.js';
 async function spawnCapture(file, args) {
     return new Promise((resolve, reject) => {
         const child = spawn(file, args, { stdio: ['ignore', 'pipe', 'pipe'] });
@@ -122,6 +123,8 @@ EOF
 export async function runInSandbox(request, options = {}) {
     const config = options.engine ? null : loadConfig();
     const engine = options.engine ?? detectEngine(config);
+    const workspace = request.workspace
+        ?? (config ? resolveSandboxTarget(request.taskRef, config.repoRoot).workspace : undefined);
     const rows = options.rows ??
         (() => {
             const fetched = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
@@ -136,6 +139,7 @@ export async function runInSandbox(request, options = {}) {
     if (options.ensureReady) {
         container = (await options.ensureReady({
             branch: request.branch,
+            workspace,
             row: found,
             allowRecreate: request.recreate ?? false
         })).container;
@@ -145,11 +149,12 @@ export async function runInSandbox(request, options = {}) {
             config,
             engine,
             branch: request.branch,
+            workspace,
             row: found,
             allowRecreate: request.recreate,
-            recreate: async (targetBranch) => {
+            recreate: async () => {
                 const { create } = await import('./commands/create.js');
-                await create([targetBranch, '--no-refresh']);
+                await create([request.taskRef, '--no-refresh']);
             }
         })).container;
     }

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

@@ -2,32 +2,33 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, spawn } from 'node:child_process';
 import { parseArgs } from 'node:util';
+import { fileURLToPath } from 'node:url';
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { listAgentClientAdapters } from '../../agent-clients/registry.js';
 import { loadConfig } from '../config.js';
-import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxImageRefreshLabel, sandboxLabel, sandboxRuntimeCapabilityLabel, shareBranchDir, shareCommonDir, shellConfigDir, worktreeDirCandidates } from '../constants.js';
+import { assertValidBranchName, containerName, containerNameCandidates, parsePositiveIntegerOption, sandboxBranchLabel, sandboxImageConfigLabel, sandboxImageRefreshLabel, sandboxLabel, sandboxRuntimeCapabilityLabel, sandboxTaskIdLabel, sandboxWorkspaceModeLabel, 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 { parseSandboxWorkspaceIdentity, resolveSandboxTarget, sameSandboxWorkspaceIdentity } from '../workspace-identity.js';
 import { createSandboxCapabilityPlan, runSandboxHooks, runBoundedSandboxHookCommand } from '../agent-client-reconciler.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 { assertSandboxTaskSource, materializeSandboxControl, materializeSandboxWorkspaceView } 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';
 import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.js';
 import { removeDirRecursive } from '../../remove-dir.js';
-import { prepareClaudeCredentials, redactCommandError, validateClaudeCredentialsEnvOverride } from '../credentials.js';
+import { redactCommandError } from '../redaction.js';
 import { detectHostTimezone } from '../host-timezone.js';
 import { buildImageSignature, buildSandboxImageArgs, isRefreshDisabled, isRefreshDue, parseImageLabels, parseRefreshTimestamp } from '../image-build.js';
-export { ensureCodexModelInheritance, ensureCodexWorkspaceTrust } from '../../agent-clients/adapters/codex-sandbox.js';
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
 const SANDBOX_ALIAS_BLOCK_END = '# <<< agent-infra managed aliases <<<';
 const CONTAINER_HOME = '/home/devuser';
@@ -64,6 +65,11 @@ const MANAGED_GITHUB_GIT_CONFIG = [
     '[url "https://github.com/"]',
     '\tinsteadOf = git@github.com:'
 ];
+function internalCliPath() {
+    const directory = path.dirname(fileURLToPath(import.meta.url));
+    const extension = path.extname(fileURLToPath(import.meta.url));
+    return path.resolve(directory, '..', '..', '..', 'bin', `internal-cli${extension}`);
+}
 function resolveToolDirs(config, tools, branch) {
     return tools.map((tool) => {
         const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -544,191 +550,6 @@ export function assertBranchAvailable(repoRoot, branch, { allowedWorktrees = [],
         }
     }
 }
-function readHostJsonSafe(filePath) {
-    if (!filePath || !fs.existsSync(filePath)) {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8'));
-        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
-    }
-}
-const CLAUDE_SETTINGS_INHERIT_TOP_LEVEL_KEYS = [
-    'model',
-    'fallbackModel',
-    'availableModels',
-    'modelOverrides',
-    'enforceAvailableModels',
-    'advisorModel',
-    'apiKeyHelper',
-    'effortLevel'
-];
-function isJsonObjectRecord(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function mergeMissingStringEnvFields(target, source) {
-    if (!isJsonObjectRecord(source.env)) {
-        return false;
-    }
-    if (Object.hasOwn(target, 'env') && !isJsonObjectRecord(target.env)) {
-        return false;
-    }
-    let targetEnv = target.env;
-    let changed = false;
-    for (const [key, value] of Object.entries(source.env)) {
-        if (typeof value !== 'string' || value === '') {
-            continue;
-        }
-        if (!targetEnv) {
-            targetEnv = {};
-            target.env = targetEnv;
-        }
-        if (!Object.hasOwn(targetEnv, key)) {
-            targetEnv[key] = value;
-            changed = true;
-        }
-    }
-    return changed;
-}
-function mergeMissingTopLevelSettings(target, source) {
-    let changed = false;
-    for (const key of CLAUDE_SETTINGS_INHERIT_TOP_LEVEL_KEYS) {
-        if (!Object.hasOwn(source, key) || Object.hasOwn(target, key)) {
-            continue;
-        }
-        const value = source[key];
-        if (value === null || value === undefined || value === '') {
-            continue;
-        }
-        target[key] = value;
-        changed = true;
-    }
-    return changed;
-}
-export function ensureClaudeOnboarding(toolDir, hostHomeDir) {
-    const claudeJsonPath = path.join(toolDir, '.claude.json');
-    let data = {};
-    if (fs.existsSync(claudeJsonPath)) {
-        try {
-            data = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8'));
-        }
-        catch {
-            // malformed JSON, start fresh
-        }
-    }
-    let changed = false;
-    if (!data.hasCompletedOnboarding) {
-        data.hasCompletedOnboarding = true;
-        changed = true;
-    }
-    if (!data.projects) {
-        data.projects = {};
-        changed = true;
-    }
-    if (!data.projects['/workspace']) {
-        data.projects['/workspace'] = {};
-        changed = true;
-    }
-    if (!data.projects['/workspace'].hasTrustDialogAccepted) {
-        data.projects['/workspace'].hasTrustDialogAccepted = true;
-        changed = true;
-    }
-    if (hostHomeDir) {
-        const hostClaudeJson = readHostJsonSafe(path.join(hostHomeDir, '.claude.json'));
-        if (hostClaudeJson
-            && typeof hostClaudeJson.model === 'string'
-            && hostClaudeJson.model !== ''
-            && !Object.hasOwn(data, 'model')) {
-            data.model = hostClaudeJson.model;
-            changed = true;
-        }
-        // Claude Code launch-pins a default effort per model generation (for
-        // example xhigh for Opus 4.7). The saved effortLevel is honored only after
-        // a top-level boolean `unpin*LaunchEffort: true` flag unlocks it, so mirror
-        // those flags here with the existing first-write semantics.
-        //
-        // Pattern matching avoids one patch per future model generation. If
-        // Anthropic changes the naming convention, this block will no-op and should
-        // be revisited.
-        if (hostClaudeJson) {
-            for (const key of Object.keys(hostClaudeJson)) {
-                if (/^unpin.*LaunchEffort$/.test(key)
-                    && hostClaudeJson[key] === true
-                    && !Object.hasOwn(data, key)) {
-                    data[key] = true;
-                    changed = true;
-                }
-            }
-        }
-    }
-    if (changed) {
-        fs.writeFileSync(claudeJsonPath, JSON.stringify(data, null, 4), 'utf8');
-    }
-}
-export function ensureClaudeSettings(toolDir, hostHomeDir) {
-    const settingsPath = path.join(toolDir, 'settings.json');
-    let data = {};
-    if (fs.existsSync(settingsPath)) {
-        try {
-            data = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
-        }
-        catch {
-            // malformed JSON, start fresh
-        }
-    }
-    let changed = false;
-    if (data.skipDangerousModePermissionPrompt !== true) {
-        data.skipDangerousModePermissionPrompt = true;
-        changed = true;
-    }
-    if (hostHomeDir) {
-        const hostSettings = readHostJsonSafe(path.join(hostHomeDir, '.claude', 'settings.json'));
-        if (hostSettings) {
-            changed = mergeMissingStringEnvFields(data, hostSettings) || changed;
-            changed = mergeMissingTopLevelSettings(data, hostSettings) || changed;
-        }
-    }
-    if (changed) {
-        fs.writeFileSync(settingsPath, JSON.stringify(data, null, 4), 'utf8');
-    }
-}
-export function ensureOpenCodeModelInheritance(toolDir, hostHomeDir) {
-    if (!hostHomeDir) {
-        return;
-    }
-    const hostConfigPath = path.join(hostHomeDir, '.config', 'opencode', 'opencode.json');
-    const hostJson = readHostJsonSafe(hostConfigPath);
-    if (!hostJson) {
-        return;
-    }
-    const sandboxConfigPath = path.join(toolDir, 'opencode.json');
-    let sandboxJson = {};
-    if (fs.existsSync(sandboxConfigPath)) {
-        const existing = readHostJsonSafe(sandboxConfigPath);
-        if (!existing) {
-            return;
-        }
-        sandboxJson = existing;
-    }
-    let changed = false;
-    for (const key of ['model', 'small_model']) {
-        if (Object.hasOwn(sandboxJson, key)) {
-            continue;
-        }
-        const value = hostJson[key];
-        if (typeof value !== 'string' || value === '') {
-            continue;
-        }
-        sandboxJson[key] = value;
-        changed = true;
-    }
-    if (changed) {
-        fs.writeFileSync(sandboxConfigPath, JSON.stringify(sandboxJson, null, 2), 'utf8');
-    }
-}
 export function sandboxAliasesPath(home) {
     return hostJoin(home, '.agent-infra', 'aliases', 'sandbox.sh');
 }
@@ -848,10 +669,10 @@ export async function create(args) {
         throw new Error(USAGE);
     }
     validateSelinuxDisableEnv();
-    validateClaudeCredentialsEnvOverride();
     const config = loadConfig();
     const [branchOrTaskId = '', base] = positionals;
-    const branch = resolveTaskBranch(branchOrTaskId, config.repoRoot);
+    const target = resolveSandboxTarget(branchOrTaskId, config.repoRoot);
+    const branch = target.branch;
     assertValidBranchName(branch);
     const effectiveConfig = {
         ...config,
@@ -866,39 +687,43 @@ export async function create(args) {
     const capabilityPlan = createSandboxCapabilityPlan(effectiveConfig);
     const tools = [...capabilityPlan.tools];
     const resolvedTools = resolveToolDirs(effectiveConfig, tools, branch);
-    // Fatal credential states still fail before filesystem/docker side effects.
-    // Missing credentials leave the selected Claude Code capability installed
-    // and mounted; only the absent live credential file is omitted.
-    const credentialOutcome = prepareClaudeCredentials(effectiveConfig.home, effectiveConfig.project, resolvedTools);
+    const prepareHookResults = await runSandboxHooks({
+        hooks: capabilityPlan.hooksByPhase.prepare,
+        phase: 'prepare',
+        context: {
+            config: effectiveConfig,
+            plan: capabilityPlan,
+            create: {
+                hostHome: effectiveConfig.home,
+                hostEnv: { ...process.env },
+                project: effectiveConfig.project,
+                resolvedTools
+            }
+        },
+        runCommand: runBoundedSandboxHookCommand
+    });
+    const prepareFailure = prepareHookResults.find((result) => result.status === 'fatal');
+    if (prepareFailure) {
+        throw new Error(prepareFailure.message ?? `Sandbox hook '${prepareFailure.hookId}' failed.`);
+    }
     const effectiveResolvedTools = resolvedTools;
     const container = containerName(effectiveConfig, branch);
     const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
     const shareCommon = shareCommonDir(effectiveConfig);
     const shareBranch = shareBranchDir(effectiveConfig, branch);
-    const preparedDockerfile = prepareDockerfile(effectiveConfig);
+    const preparedDockerfile = prepareDockerfile(effectiveConfig, capabilityPlan.image);
     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') {
-        p.log.warn('Claude Code credentials not found on host - creating this sandbox WITHOUT Claude Code credentials.\n'
-            + '  Claude Code is still installed in the image but will not be authenticated.\n'
-            + '  To enable it: run "claude" once on the host to complete login, then re-run "ai sandbox create".');
+    for (const result of prepareHookResults) {
+        if (result.status === 'warning' && result.message)
+            p.log.warn(result.message);
     }
     try {
         p.log.step('Checking container engine...');
-        const prepareHookResults = await runSandboxHooks({
-            hooks: capabilityPlan.hooksByPhase.prepare,
-            phase: 'prepare',
-            context: { config: effectiveConfig, plan: capabilityPlan },
-            runCommand: runBoundedSandboxHookCommand
-        });
-        const prepareFailure = prepareHookResults.find((result) => result.status === 'fatal');
-        if (prepareFailure) {
-            throw new Error(prepareFailure.message ?? `Sandbox hook '${prepareFailure.hookId}' failed.`);
-        }
         await ensureDocker(effectiveConfig, (detail) => {
             p.log.info(`  ${detail}`);
         });
@@ -1048,6 +873,32 @@ export async function create(args) {
                     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;
+                                throw new Error(`SANDBOX_WORKSPACE_IDENTITY_CONFLICT: container '${name}' is ${existingDescription}, `
+                                    + `but this request is ${requestedDescription}. Run 'ai sandbox rm ${branch}' and retry.`);
+                            }
+                        }
                         message('Removing old container instance...');
                         for (const name of matchedContainers) {
                             runSafeEngine(engine, 'docker', ['stop', name]);
@@ -1091,6 +942,8 @@ export async function create(args) {
                                 plan: capabilityPlan,
                                 create: {
                                     hostHome: effectiveConfig.home,
+                                    hostEnv: { ...process.env },
+                                    project: effectiveConfig.project,
                                     resolvedTools: effectiveResolvedTools
                                 }
                             },
@@ -1101,22 +954,22 @@ export async function create(args) {
                             throw new Error(beforeCreateFailure.message
                                 ?? `Sandbox hook '${beforeCreateFailure.hookId}' failed.`);
                         }
-                        const claudeCodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'claude-code');
-                        if (claudeCodeEntry) {
-                            ensureClaudeOnboarding(claudeCodeEntry.dir, effectiveConfig.home);
-                            ensureClaudeSettings(claudeCodeEntry.dir, effectiveConfig.home);
-                            // prepareClaudeCredentials wrote OAuth credentials or confirmed
-                            // provider/API settings are enough for Claude Code. If no usable
-                            // auth was present, the claude-code entry was removed above.
-                        }
-                        const opencodeEntry = effectiveResolvedTools.find(({ tool }) => tool.id === 'opencode');
-                        if (opencodeEntry) {
-                            // The TUI reads <toolDir>/opencode.json via OPENCODE_CONFIG pinned in tools.js.
-                            ensureOpenCodeModelInheritance(opencodeEntry.dir, effectiveConfig.home);
-                        }
                         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 workspaceDir = path.join(effectiveConfig.repoRoot, '.agents', 'workspace');
+                        const workspaceView = materializeSandboxWorkspaceView({
+                            base: effectiveConfig.workspaceViewBase,
+                            project: effectiveConfig.project,
+                            container,
+                            identity: target.workspace
+                        });
+                        const control = materializeSandboxControl({
+                            base: effectiveConfig.controlBase,
+                            repoRoot: effectiveConfig.repoRoot,
+                            project: effectiveConfig.project,
+                            container,
+                            branch,
+                            identity: target.workspace
+                        });
                         hostShellConfig = prepareHostShellConfig({
                             home: effectiveConfig.home,
                             project: effectiveConfig.project,
@@ -1125,7 +978,15 @@ export async function create(args) {
                         });
                         const coreVolumes = sandboxCoreBindMounts(effectiveConfig, branch, {
                             worktree,
-                            shellConfigHostDir: hostShellConfig.hostDir
+                            shellConfigHostDir: hostShellConfig.hostDir,
+                            workspaceViewRoot: workspaceView.root,
+                            controlDir: control.channelDir,
+                            ...(target.workspace.mode === 'task-bound'
+                                ? {
+                                    taskSource: assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId),
+                                    taskId: target.workspace.taskId
+                                }
+                                : {})
                         }).flatMap(({ hostPaths, containerPath, readOnly }) => [
                             '-v',
                             volumeArg(engine, hostPaths[0], containerPath, readOnly ? ':ro' : '')
@@ -1157,7 +1018,6 @@ export async function create(args) {
                             '-v',
                             volumeArg(engine, hostPath, path.posix.join(tool.containerMount, containerSubpath))
                         ]));
-                        fs.mkdirSync(workspaceDir, { recursive: true });
                         fs.mkdirSync(shareCommon, { recursive: true });
                         fs.mkdirSync(shareBranch, { recursive: true });
                         fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
@@ -1179,6 +1039,20 @@ export async function create(args) {
                             '--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_DIR=/run/agent-infra/control',
+                            '--label',
                             `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
                             ...coreVolumes,
                             ...buildClipboardVolumeArgs(engine, effectiveConfig.home),
@@ -1195,6 +1069,12 @@ export async function create(args) {
                             '/workspace',
                             effectiveConfig.imageName
                         ]);
+                        const broker = spawn(process.execPath, [internalCliPath(), 'sandbox-control', 'serve', '--manifest', control.manifestPath], { cwd: effectiveConfig.repoRoot, detached: true, stdio: 'ignore' });
+                        broker.once('error', () => {
+                            // Fresh readiness verification below remains the source of truth;
+                            // consume detached spawn errors so they cannot crash the command.
+                        });
+                        broker.unref();
                         createdTmpfsSeedPlan = tmpfsSeedPlan;
                     }
                     finally {
@@ -1277,10 +1157,11 @@ export async function create(args) {
         preparedDockerfile.cleanup();
     }
     p.log.step('Verifying setup...');
-    assertFreshSandboxReady({
+    await assertFreshSandboxReady({
         config: effectiveConfig,
         engine,
         branch,
+        workspace: target.workspace,
         container,
         copiedEntries: createdTmpfsSeedPlan
     });