@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/lib/sandbox/commands/create.ts

@@ -2,9 +2,10 @@ 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 type { ExecFileSyncOptions, StdioOptions } 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.ts';
@@ -20,6 +21,8 @@ import {
   sandboxImageRefreshLabel,
   sandboxLabel,
   sandboxRuntimeCapabilityLabel,
+  sandboxTaskIdLabel,
+  sandboxWorkspaceModeLabel,
   shareBranchDir,
   shareCommonDir,
   shellConfigDir,
@@ -44,7 +47,11 @@ import {
   runSafeEngine,
   runVerboseEngine
 } from '../shell.ts';
-import { resolveTaskBranch } from '../task-resolver.ts';
+import {
+  parseSandboxWorkspaceIdentity,
+  resolveSandboxTarget,
+  sameSandboxWorkspaceIdentity
+} from '../workspace-identity.ts';
 import {
   createSandboxCapabilityPlan,
   runSandboxHooks,
@@ -64,16 +71,17 @@ import {
 } from '../recovery.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
 import { sandboxCoreBindMounts } from '../mounts.ts';
+import {
+  assertSandboxTaskSource,
+  materializeSandboxControl,
+  materializeSandboxWorkspaceView
+} from '../workspace-view.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
 import { ensureSandboxDiscoveryReadmes } from '../readme-scaffold.ts';
 import { removeDirRecursive } from '../../remove-dir.ts';
-import {
-  prepareClaudeCredentials,
-  redactCommandError,
-  validateClaudeCredentialsEnvOverride
-} from '../credentials.ts';
+import { redactCommandError } from '../redaction.ts';
 import { detectHostTimezone } from '../host-timezone.ts';
 import {
   buildImageSignature,
@@ -84,10 +92,6 @@ import {
   parseRefreshTimestamp
 } from '../image-build.ts';
 
-export {
-  ensureCodexModelInheritance,
-  ensureCodexWorkspaceTrust
-} from '../../agent-clients/adapters/codex-sandbox.ts';
 
 const SANDBOX_ALIAS_BLOCK_BEGIN = '# >>> agent-infra managed aliases >>>';
 const SANDBOX_ALIAS_BLOCK_END = '# <<< agent-infra managed aliases <<<';
@@ -133,7 +137,6 @@ type TmpfsSeedPlanEntry = TmpfsSeedEntry & {
   volumeArgs: string[];
 };
 type RuntimeCheck = { name: string; cmd: string[] };
-type JsonObject = Record<string, unknown>;
 type GpgCache = { pub: Buffer; sec: Buffer } | null;
 type ExecSyncOptions = ExecFileSyncOptions & {
   input?: Buffer | string;
@@ -154,6 +157,12 @@ type HostShellConfig = {
   mounts: Array<{ hostPath: string; containerPath: string }>;
 };
 
+function internalCliPath(): string {
+  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: Pick<SandboxCreateConfig, 'project'>, tools: SandboxTool[], branch: string): ResolvedTool[] {
   return tools.map((tool) => {
     const candidates = toolConfigDirCandidates(tool, config.project, branch);
@@ -807,209 +816,6 @@ export function assertBranchAvailable(
   }
 }
 
-function readHostJsonSafe(filePath: string): JsonObject | null {
-  if (!filePath || !fs.existsSync(filePath)) {
-    return null;
-  }
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, 'utf8')) as unknown;
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed as JsonObject : null;
-  } catch {
-    return null;
-  }
-}
-
-const CLAUDE_SETTINGS_INHERIT_TOP_LEVEL_KEYS = [
-  'model',
-  'fallbackModel',
-  'availableModels',
-  'modelOverrides',
-  'enforceAvailableModels',
-  'advisorModel',
-  'apiKeyHelper',
-  'effortLevel'
-];
-
-function isJsonObjectRecord(value: unknown): value is JsonObject {
-  return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-
-function mergeMissingStringEnvFields(target: JsonObject, source: JsonObject): boolean {
-  if (!isJsonObjectRecord(source.env)) {
-    return false;
-  }
-  if (Object.hasOwn(target, 'env') && !isJsonObjectRecord(target.env)) {
-    return false;
-  }
-
-  let targetEnv = target.env as JsonObject | undefined;
-  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: JsonObject, source: JsonObject): boolean {
-  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: string, hostHomeDir?: string): void {
-  const claudeJsonPath = path.join(toolDir, '.claude.json');
-  let data: JsonObject & {
-    hasCompletedOnboarding?: boolean;
-    projects?: Record<string, { hasTrustDialogAccepted?: boolean }>;
-    model?: string;
-  } = {};
-  if (fs.existsSync(claudeJsonPath)) {
-    try {
-      data = JSON.parse(fs.readFileSync(claudeJsonPath, 'utf8')) as typeof data;
-    } 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: string, hostHomeDir?: string): void {
-  const settingsPath = path.join(toolDir, 'settings.json');
-  let data: JsonObject & { skipDangerousModePermissionPrompt?: boolean } = {};
-  if (fs.existsSync(settingsPath)) {
-    try {
-      data = JSON.parse(fs.readFileSync(settingsPath, 'utf8')) as typeof data;
-    } 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: string, hostHomeDir?: string): void {
-  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: JsonObject = {};
-  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: string): string {
   return hostJoin(home, '.agent-infra', 'aliases', 'sandbox.sh');
 }
@@ -1195,11 +1001,10 @@ export async function create(args: string[]): Promise<void> {
   }
 
   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,
@@ -1214,20 +1019,31 @@ export async function create(args: string[]): Promise<void> {
   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);
@@ -1237,26 +1053,12 @@ export async function create(args: string[]): Promise<void> {
   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: string) => {
       p.log.info(`  ${detail}`);
     });
@@ -1431,6 +1233,33 @@ export async function create(args: string[]): Promise<void> {
             .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: Record<string, string> = {};
+              try {
+                labels = JSON.parse(rawLabels) as Record<string, string>;
+              } 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]);
@@ -1485,6 +1314,8 @@ export async function create(args: string[]): Promise<void> {
                 plan: capabilityPlan,
                 create: {
                   hostHome: effectiveConfig.home,
+                  hostEnv: { ...process.env },
+                  project: effectiveConfig.project,
                   resolvedTools: effectiveResolvedTools
                 }
               },
@@ -1499,26 +1330,27 @@ export async function create(args: string[]): Promise<void> {
                 ?? `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,
+              worktreeRoot: worktree,
+              project: effectiveConfig.project,
+              container,
+              branch,
+              identity: target.workspace
+            });
             hostShellConfig = prepareHostShellConfig({
               home: effectiveConfig.home,
               project: effectiveConfig.project,
@@ -1527,7 +1359,18 @@ export async function create(args: string[]): Promise<void> {
             });
             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' : '')
@@ -1564,7 +1407,6 @@ export async function create(args: string[]): Promise<void> {
                 ])
             );
 
-            fs.mkdirSync(workspaceDir, { recursive: true });
             fs.mkdirSync(shareCommon, { recursive: true });
             fs.mkdirSync(shareBranch, { recursive: true });
             fs.mkdirSync(clipboardHostDir(effectiveConfig.home), { recursive: true, mode: 0o700 });
@@ -1591,6 +1433,20 @@ export async function create(args: string[]): Promise<void> {
               '--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),
@@ -1611,6 +1467,16 @@ export async function create(args: string[]): Promise<void> {
               '/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 {
             envFile.cleanup();
@@ -1713,10 +1579,11 @@ export async function create(args: string[]): Promise<void> {
   }
 
   p.log.step('Verifying setup...');
-  assertFreshSandboxReady({
+  await assertFreshSandboxReady({
     config: effectiveConfig,
     engine,
     branch,
+    workspace: target.workspace,
     container,
     copiedEntries: createdTmpfsSeedPlan
   });

package/lib/sandbox/commands/enter.ts

@@ -12,23 +12,16 @@ import {
   runBoundedSandboxHookCommand,
   runSandboxHooks
 } from '../agent-client-reconciler.ts';
-import {
-  formatCredentialWarnings,
-  formatRemaining,
-  hasClaudeProviderAuth,
-  reconcileClaudeCredentials,
-  redactCommandError,
-  validateClaudeCredentialsEnvOverride
-} from '../credentials.ts';
 import { runInteractiveEngine } from '../shell.ts';
 import { dotfilesCacheDir, materializeDotfiles } from '../dotfiles.ts';
+import { redactCommandError } from '../redaction.ts';
 import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.ts';
 import { detectHostTimezone } from '../host-timezone.ts';
 import {
   fetchSandboxRows,
-  resolveBranchArg,
   selectSandboxContainer,
 } from './list-running.ts';
+import { resolveSandboxTarget } from '../workspace-identity.ts';
 
 const USAGE = `Usage: ai sandbox exec [--recreate] <branch | TASK-id | N> [cmd...]
 
@@ -98,37 +91,6 @@ export function runSandboxInteractive(params: {
   return runBridge({ engine, dockerArgs, container, home });
 }
 
-export function formatCredentialSyncStatus(
-  result: ReturnType<typeof reconcileClaudeCredentials>,
-  isTTY = process.stderr.isTTY,
-  providerAuthAvailable = false
-): string | null {
-  if (providerAuthAvailable && (result.status === 'STALE_ACCESS' || result.status === 'MISSING')) {
-    return null;
-  }
-  if (result.status === 'STALE_ACCESS') {
-    return 'Warning: Claude Code credentials on host appear stale. Run "ai sandbox refresh" or "claude /login" to renew.\n';
-  }
-  if (result.status === 'MISSING') {
-    return 'Warning: Claude Code credentials missing on host. Run "claude /login" to authenticate.\n';
-  }
-  if (result.status === 'KEYCHAIN_WRITE_FAILED') {
-    return `Warning: A sandbox refresh produced newer credentials but host Keychain write failed (${formatCredentialWarnings(result.warnings)}). Run "ai sandbox refresh" again or "claude /status" on the host to retry.\n`;
-  }
-  if (result.status === 'KEYCHAIN_LOCKED' || result.status === 'KEYCHAIN_ERROR') {
-    return 'Warning: Host keychain is unavailable; Claude credential sync skipped. Run "ai sandbox refresh" for details.\n';
-  }
-  if (result.status === 'OK' && result.authoritative !== 'host') {
-    const message = `Synced Claude Code credentials from sandbox refresh back to host (expires in ${formatRemaining(result.expiresAt)})`;
-    return isTTY ? `\x1b[2m${message}\x1b[0m\n` : `${message}\n`;
-  }
-  if (result.status === 'OK' && result.filesWritten.length > 0) {
-    const message = `Synced Claude Code credentials from host Keychain (expires in ${formatRemaining(result.expiresAt)})`;
-    return isTTY ? `\x1b[2m${message}\x1b[0m\n` : `${message}\n`;
-  }
-  return null;
-}
-
 export function parseEnterArgs(args: string[]): {
   target: string;
   command: string[];
@@ -157,10 +119,10 @@ export async function enter(args: string[]): Promise<number> {
   }
 
   const config = loadConfig();
-  validateClaudeCredentialsEnvOverride();
   const engine = detectEngine(config);
   const parsed = parseEnterArgs(args);
-  const branch = resolveBranchArg(parsed.target, { repoRoot: config.repoRoot });
+  const target = resolveSandboxTarget(parsed.target, config.repoRoot);
+  const branch = target.branch;
   assertValidBranchName(branch);
 
   const { running, nonRunning } = fetchSandboxRows(
@@ -182,11 +144,12 @@ export async function enter(args: string[]): Promise<number> {
     config,
     engine,
     branch,
+    workspace: target.workspace,
     row: found,
     allowRecreate: parsed.recreate,
-    recreate: async (targetBranch) => {
+    recreate: async () => {
       const { create } = await import('./create.ts');
-      await create([targetBranch, '--no-refresh']);
+      await create([target.requestedRef, '--no-refresh']);
     }
   });
   const container = ready.container;
@@ -195,7 +158,11 @@ export async function enter(args: string[]): Promise<number> {
   const enterHookResults = await runSandboxHooks({
     hooks: capabilityPlan.hooksByPhase['before-enter'],
     phase: 'before-enter',
-    context: { config, plan: capabilityPlan },
+    context: {
+      config,
+      plan: capabilityPlan,
+      enter: { hostHome: config.home, hostEnv: { ...process.env } }
+    },
     runCommand: runBoundedSandboxHookCommand
   });
   for (const result of enterHookResults) {
@@ -207,20 +174,7 @@ export async function enter(args: string[]): Promise<number> {
         `Warning: ${result.message ?? `Sandbox hook '${result.hookId}' did not complete.`}\n`
       );
     }
-  }
-
-  if (capabilityPlan.selectedAgentClients.some((adapter) => adapter.id === 'claude-code')) {
-    try {
-      // Scan all projects so a refresh from a neighbouring sandbox can still flow back to the host.
-      const providerAuthAvailable = hasClaudeProviderAuth(config.home);
-      const result = reconcileClaudeCredentials(config.home);
-      const message = formatCredentialSyncStatus(result, process.stderr.isTTY, providerAuthAvailable);
-      if (message) {
-        process.stderr.write(message);
-      }
-    } catch (error) {
-      process.stderr.write(`Warning: Failed to sync Claude Code credentials: ${redactCommandError(error instanceof Error ? error.message : 'unknown error')}\n`);
-    }
+    if (result.message && result.status !== 'warning') process.stderr.write(result.message);
   }
 
   const envFlags = [...terminalEnvFlags(), ...hostTimezoneEnvFlags()];