@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/lib/sandbox/control/server.ts

@@ -0,0 +1,155 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getProcessStartTime } from '../../server/process-state.ts';
+import { createTask } from '../../task/create-service.ts';
+import { assertGitWorktreeBinding } from '../../git/worktree-identity.ts';
+import {
+  bindSandboxControlTask,
+  validateSandboxControlRequest,
+  type SandboxControlManifest,
+  type SandboxControlResponse
+} from './protocol.ts';
+
+function readManifest(manifestPath: string): SandboxControlManifest {
+  const stat = fs.lstatSync(manifestPath);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as SandboxControlManifest;
+  if (manifest.version !== 2) {
+    throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 2; recreate the sandbox');
+  }
+  if (
+    typeof manifest.repoRoot !== 'string'
+    || typeof manifest.worktreeRoot !== 'string'
+    || typeof manifest.channelDir !== 'string'
+    || typeof manifest.token !== 'string'
+  ) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  if (path.resolve(manifest.channelDir) !== path.join(path.dirname(path.resolve(manifestPath)), 'channel')) {
+    throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  }
+  return manifest;
+}
+
+function assertRealDirectory(directory: string, parent?: string): void {
+  const stat = fs.lstatSync(directory);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+  if (parent && path.dirname(fs.realpathSync.native(directory)) !== fs.realpathSync.native(parent)) {
+    throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+  }
+}
+
+function writeResponse(directory: string, response: SandboxControlResponse): void {
+  const temporary = path.join(directory, `.${response.id}.tmp`);
+  fs.writeFileSync(temporary, `${JSON.stringify(response)}\n`, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(temporary, path.join(directory, `${response.id}.json`));
+}
+
+export function sandboxControlSafeEnv(env: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
+  return Object.fromEntries(
+    Object.entries(env).filter(
+      ([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')
+    )
+  );
+}
+
+function consumeRequest(directory: string, id: string): void {
+  try {
+    fs.writeFileSync(path.join(directory, id), '', { flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+      throw new Error('SANDBOX_CONTROL_REQUEST_REPLAYED');
+    }
+    throw error;
+  }
+}
+
+export function serveSandboxControl(manifestPath: string, signal: AbortSignal = new AbortController().signal): void {
+  const manifest = readManifest(manifestPath);
+  assertGitWorktreeBinding(manifest.repoRoot, manifest.worktreeRoot, manifest.branch);
+  const brokerPath = path.join(path.dirname(manifestPath), 'broker.json');
+  const startTime = getProcessStartTime(process.pid);
+  if (!startTime) throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
+  fs.writeFileSync(brokerPath, `${JSON.stringify({
+    version: 1,
+    pid: process.pid,
+    startTime,
+    token: manifest.token
+  })}\n`, { mode: 0o600, flag: 'wx' });
+  const requestsDir = path.join(manifest.channelDir, 'requests');
+  const responsesDir = path.join(manifest.channelDir, 'responses');
+  const consumedDir = path.join(path.dirname(manifestPath), 'consumed');
+  assertRealDirectory(manifest.channelDir);
+  fs.mkdirSync(requestsDir, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(responsesDir, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
+  assertRealDirectory(requestsDir, manifest.channelDir);
+  assertRealDirectory(responsesDir, manifest.channelDir);
+  assertRealDirectory(consumedDir, path.dirname(manifestPath));
+  while (!signal.aborted) {
+    const current = readManifest(manifestPath);
+    if (current.token !== manifest.token) return;
+    assertGitWorktreeBinding(current.repoRoot, current.worktreeRoot, current.branch);
+    assertRealDirectory(requestsDir, manifest.channelDir);
+    assertRealDirectory(responsesDir, manifest.channelDir);
+    for (const name of fs.readdirSync(requestsDir).sort()) {
+      if (!/^[a-f0-9-]{16,64}\.json$/.test(name)) continue;
+      const requestPath = path.join(requestsDir, name);
+      let id = name.slice(0, -5);
+      let response: SandboxControlResponse;
+      try {
+        const stat = fs.lstatSync(requestPath);
+        if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_REQUEST_INVALID');
+        const request = validateSandboxControlRequest(
+          JSON.parse(fs.readFileSync(requestPath, 'utf8')),
+          manifest
+        );
+        id = request.id;
+        consumeRequest(consumedDir, id);
+        if (request.family === 'task-create') {
+          const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
+          response = {
+            version: 1, id,
+            exitCode: result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0,
+            stdout: `${JSON.stringify(result)}\n`, stderr: ''
+          };
+        } else {
+          const boundArgs = bindSandboxControlTask(request, manifest.taskId!);
+          if (request.family === 'task-orchestration') {
+            boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
+          }
+          const result = spawnSync(
+            process.execPath,
+            ['--experimental-strip-types', '--no-warnings', process.argv[1]!, request.family, ...boundArgs],
+            {
+              cwd: manifest.repoRoot,
+              encoding: 'utf8',
+              env: sandboxControlSafeEnv()
+            }
+          );
+          response = {
+            version: 1,
+            id,
+            exitCode: result.status ?? 1,
+            stdout: result.stdout ?? '',
+            stderr: result.stderr ?? ''
+          };
+        }
+      } catch (error) {
+        response = {
+          version: 1,
+          id,
+          exitCode: 1,
+          stdout: '',
+          stderr: `${error instanceof Error ? error.message : String(error)}\n`
+        };
+      }
+      try {
+        fs.unlinkSync(requestPath);
+        writeResponse(responsesDir, response);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      }
+    }
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+  }
+}

package/lib/sandbox/dockerfile.ts

@@ -9,6 +9,23 @@ const RUNTIMES_DIR = path.join(
   path.dirname(fileURLToPath(import.meta.url)),
   'runtimes'
 );
+const AGENT_CLIENT_RUNTIMES_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'agent-clients',
+  'adapters',
+  'runtimes'
+);
+
+type DockerfileImageContribution = Readonly<{
+  dockerfileFragments: readonly string[];
+  dotfilesExclusions: readonly string[];
+}>;
+
+const EMPTY_IMAGE_CONTRIBUTION: DockerfileImageContribution = Object.freeze({
+  dockerfileFragments: Object.freeze([]),
+  dotfilesExclusions: Object.freeze([])
+});
 
 type DockerfileConfig = {
   repoRoot: string;
@@ -29,7 +46,29 @@ export function availableRuntimes(): string[] {
     .sort();
 }
 
-function dockerfileContent(config: DockerfileConfig): string {
+function exclusionsFragment(exclusions: readonly string[]): string {
+  return [
+    "RUN mkdir -p /etc/agent-infra && cat > /etc/agent-infra/dotfiles-exclusions <<'EXCLUSIONS'",
+    ...exclusions,
+    'EXCLUSIONS'
+  ].join('\n');
+}
+
+function adapterFragmentPath(fragment: string): string {
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(fragment)) {
+    throw new Error(`Invalid Agent Client Dockerfile fragment: ${fragment}`);
+  }
+  const fragmentPath = path.join(AGENT_CLIENT_RUNTIMES_DIR, `${fragment}.dockerfile`);
+  if (!fs.existsSync(fragmentPath)) {
+    throw new Error(`Unknown Agent Client Dockerfile fragment: ${fragment}`);
+  }
+  return fragmentPath;
+}
+
+function dockerfileContent(
+  config: DockerfileConfig,
+  image: DockerfileImageContribution = EMPTY_IMAGE_CONTRIBUTION
+): string {
   if (config.dockerfile) {
     const customPath = path.resolve(config.repoRoot, config.dockerfile);
     if (!fs.existsSync(customPath)) {
@@ -48,26 +87,37 @@ function dockerfileContent(config: DockerfileConfig): string {
   }
 
   const fragments = [
-    'base.dockerfile',
-    ...config.runtimes.map((runtime) => `${runtime}.dockerfile`),
-    'ai-tools.dockerfile'
+    fs.readFileSync(path.join(RUNTIMES_DIR, 'base.dockerfile'), 'utf8').trimEnd(),
+    exclusionsFragment(image.dotfilesExclusions),
+    ...image.dockerfileFragments.map((fragment) =>
+      fs.readFileSync(adapterFragmentPath(fragment), 'utf8').trimEnd()
+    ),
+    ...config.runtimes.map((runtime) =>
+      fs.readFileSync(path.join(RUNTIMES_DIR, `${runtime}.dockerfile`), 'utf8').trimEnd()
+    ),
+    fs.readFileSync(path.join(RUNTIMES_DIR, 'ai-tools.dockerfile'), 'utf8').trimEnd()
   ];
 
   const content = fragments
-    .map((fragment) => fs.readFileSync(path.join(RUNTIMES_DIR, fragment), 'utf8').trimEnd())
     .join('\n\n');
 
   return `${content}\n`;
 }
 
-export function dockerfileSignature(config: DockerfileConfig): string {
+export function dockerfileSignature(
+  config: DockerfileConfig,
+  image: DockerfileImageContribution = EMPTY_IMAGE_CONTRIBUTION
+): string {
   return createHash('sha256')
-    .update(dockerfileContent(config))
+    .update(dockerfileContent(config, image))
     .digest('hex')
     .slice(0, 12);
 }
 
-export function prepareDockerfile(config: DockerfileConfig): { path: string; signature: string; cleanup: () => void } {
+export function prepareDockerfile(
+  config: DockerfileConfig,
+  image: DockerfileImageContribution = EMPTY_IMAGE_CONTRIBUTION
+): { path: string; signature: string; cleanup: () => void } {
   if (config.dockerfile) {
     const customPath = path.resolve(config.repoRoot, config.dockerfile);
     if (!fs.existsSync(customPath)) {
@@ -76,26 +126,29 @@ export function prepareDockerfile(config: DockerfileConfig): { path: string; sig
 
     return {
       path: customPath,
-      signature: dockerfileSignature(config),
+      signature: dockerfileSignature(config, image),
       cleanup() {}
     };
   }
 
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), `${config.project}-sandbox-`));
   const tempPath = path.join(tempDir, 'Dockerfile');
-  fs.writeFileSync(tempPath, dockerfileContent(config), 'utf8');
+  fs.writeFileSync(tempPath, dockerfileContent(config, image), 'utf8');
 
   return {
     path: tempPath,
-    signature: dockerfileSignature(config),
+    signature: dockerfileSignature(config, image),
     cleanup() {
       removeDirRecursive(tempDir);
     }
   };
 }
 
-export function composeDockerfile(config: DockerfileConfig): string {
-  const content = dockerfileContent(config);
+export function composeDockerfile(
+  config: DockerfileConfig,
+  image: DockerfileImageContribution = EMPTY_IMAGE_CONTRIBUTION
+): string {
+  const content = dockerfileContent(config, image);
 
   const tempPath = path.join(os.tmpdir(), `${config.project}-sandbox.Dockerfile`);
   fs.writeFileSync(tempPath, content, 'utf8');

package/lib/sandbox/mounts.ts

@@ -19,9 +19,16 @@ export function sandboxCoreBindMounts(
     'repoRoot' | 'worktreeBase' | 'shareBase' | 'shellConfigBase'
   >,
   branch: string,
-  overrides: { worktree?: string; shellConfigHostDir?: string } = {}
+  overrides: {
+    worktree?: string;
+    shellConfigHostDir?: string;
+    workspaceViewRoot: string;
+    controlDir: string;
+    taskSource?: string;
+    taskId?: string;
+  }
 ): SandboxBindMountDeclaration[] {
-  return [
+  const mounts: SandboxBindMountDeclaration[] = [
     {
       hostPaths: overrides.worktree
         ? [overrides.worktree]
@@ -30,9 +37,9 @@ export function sandboxCoreBindMounts(
       readOnly: false
     },
     {
-      hostPaths: [path.join(config.repoRoot, '.agents', 'workspace')],
+      hostPaths: [overrides.workspaceViewRoot],
       containerPath: '/workspace/.agents/workspace',
-      readOnly: false
+      readOnly: true
     },
     {
       hostPaths: [shareCommonDir(config)],
@@ -52,4 +59,17 @@ export function sandboxCoreBindMounts(
       readOnly: true
     }
   ];
+  if (overrides.taskSource && overrides.taskId) {
+    mounts.splice(2, 0, {
+      hostPaths: [overrides.taskSource],
+      containerPath: path.posix.join('/workspace/.agents/workspace/active', overrides.taskId),
+      readOnly: false
+    });
+  }
+  mounts.push({
+    hostPaths: [overrides.controlDir],
+    containerPath: '/run/agent-infra/control',
+    readOnly: false
+  });
+  return mounts;
 }

package/lib/sandbox/recovery.ts

@@ -1,10 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 import {
   containerNameCandidates,
   sandboxBranchLabel,
   sandboxLabel,
-  sandboxRuntimeCapabilityLabel
+  sandboxRuntimeCapabilityLabel,
+  sandboxTaskIdLabel,
+  sandboxWorkspaceModeLabel
 } from './constants.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import {
@@ -17,6 +21,16 @@ import type {
 import type { SandboxConfig } from './config.ts';
 import { toEnginePath } from './engines/wsl2-paths.ts';
 import { sandboxCoreBindMounts } from './mounts.ts';
+import {
+  assertSandboxTaskSource,
+  sandboxControlPaths,
+  sandboxWorkspaceViewPaths
+} from './workspace-view.ts';
+import {
+  parseSandboxWorkspaceIdentity,
+  sameSandboxWorkspaceIdentity,
+  type SandboxWorkspaceIdentity
+} from './workspace-identity.ts';
 import { runEngine, runOkEngine, runVerboseEngine } from './shell.ts';
 import {
   declaredTmpfsSeedEntries,
@@ -31,6 +45,7 @@ import {
   startSandboxContainer,
   type SandboxRow
 } from './commands/list-running.ts';
+import { processIdentityMatches } from '../server/process-state.ts';
 
 export type SandboxRecoveryFinding = {
   repairKind: 'permissions' | 'missing-seed' | 'builtin-link' | 'hard-failure';
@@ -109,6 +124,7 @@ type EnsureSandboxReadyParams = {
   config: SandboxConfig;
   engine: string;
   branch: string;
+  workspace?: SandboxWorkspaceIdentity;
   row: SandboxRow;
   allowRecreate?: boolean;
   recreate?: (branch: string) => Promise<void>;
@@ -123,6 +139,54 @@ type ExpectedMount = {
   expectedRW: boolean;
 };
 
+function ensureSandboxControlBroker(params: {
+  config: SandboxConfig;
+  container: string;
+  workspace: SandboxWorkspaceIdentity;
+}): void {
+  const control = sandboxControlPaths({
+    base: params.config.controlBase ?? path.join(params.config.home, '.agent-infra', 'sandbox-control'),
+    project: params.config.project,
+    container: params.container,
+    identity: params.workspace
+  });
+  if (!fs.existsSync(control.manifestPath)) return;
+  const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8')) as { token?: unknown };
+  const brokerPath = path.join(control.root, 'broker.json');
+  try {
+    const broker = JSON.parse(fs.readFileSync(brokerPath, 'utf8')) as {
+      version?: unknown;
+      pid?: unknown;
+      startTime?: unknown;
+      token?: unknown;
+    };
+    if (
+      broker.version === 1
+      && typeof broker.pid === 'number'
+      && typeof broker.startTime === 'string'
+      && broker.token === manifest.token
+      && processIdentityMatches({ version: 1, pid: broker.pid, startTime: broker.startTime })
+    ) return;
+  } catch {
+    // A missing, stale, or malformed broker record is replaced below.
+  }
+  fs.rmSync(brokerPath, { force: true });
+  const directory = path.dirname(fileURLToPath(import.meta.url));
+  const extension = path.extname(fileURLToPath(import.meta.url));
+  const internalCli = path.resolve(directory, '..', '..', 'bin', `internal-cli${extension}`);
+  const child = spawn(
+    process.execPath,
+    [internalCli, 'sandbox-control', 'serve', '--manifest', control.manifestPath],
+    { cwd: params.config.repoRoot, detached: true, stdio: 'ignore' }
+  );
+  child.once('error', () => {
+    // Readiness remains fail-closed; a later control request reports the
+    // unavailable broker without turning this detached spawn into an
+    // unhandled process error.
+  });
+  child.unref();
+}
+
 function findingKey(finding: SandboxRecoveryFinding): string {
   return `${finding.repairKind}:${finding.path ?? finding.seed?.targetPath ?? finding.message}`;
 }
@@ -297,11 +361,34 @@ function hostSourceAccessible(hostPath: string, writable: boolean): boolean {
 function expectedMounts(params: {
   config: SandboxConfig;
   branch: string;
+  container: string;
+  workspace: SandboxWorkspaceIdentity;
   tools: readonly SandboxTool[];
   actualMounts: Map<string, DockerMount>;
 }): ExpectedMount[] {
   const { config, branch, tools, actualMounts } = params;
-  const core = sandboxCoreBindMounts(config, branch).map((mount) => ({
+  const view = sandboxWorkspaceViewPaths({
+    base: config.workspaceViewBase ?? path.join(config.home, '.agent-infra', 'workspace-views'),
+    project: config.project,
+    container: params.container,
+    identity: params.workspace
+  });
+  const control = sandboxControlPaths({
+    base: config.controlBase ?? path.join(config.home, '.agent-infra', 'sandbox-control'),
+    project: config.project,
+    container: params.container,
+    identity: params.workspace
+  });
+  const core = sandboxCoreBindMounts(config, branch, {
+    workspaceViewRoot: view.root,
+    controlDir: control.channelDir,
+    ...(params.workspace.mode === 'task-bound'
+      ? {
+        taskSource: assertSandboxTaskSource(config.repoRoot, params.workspace.taskId),
+        taskId: params.workspace.taskId
+      }
+      : {})
+  }).map((mount) => ({
     path: mount.containerPath,
     expectedType: 'bind' as const,
     hostPaths: mount.hostPaths,
@@ -399,6 +486,7 @@ export function collectSandboxRecoverySnapshot(params: {
   config: SandboxConfig;
   engine: string;
   branch: string;
+  workspace?: SandboxWorkspaceIdentity;
   container: string;
   deps?: RecoveryCommandDeps;
 }): SandboxRecoverySnapshot {
@@ -427,6 +515,7 @@ export function collectSandboxRecoverySnapshot(params: {
     }
   }
   const capabilityPlan = createSandboxCapabilityPlan(params.config);
+  const workspace = params.workspace ?? { mode: 'branch-only' as const };
   const tools = [...capabilityPlan.tools];
   const seeds = declaredTmpfsSeedEntries(tools).map((seed) => {
     const mounted = mountsByDestination.get(seed.stagingPath)?.Type === 'bind';
@@ -460,6 +549,10 @@ export function collectSandboxRecoverySnapshot(params: {
   }));
   const labels = inspection.Config?.Labels ?? {};
   const branchLabel = labels[sandboxBranchLabel(params.config)];
+  const containerWorkspace = parseSandboxWorkspaceIdentity(labels, {
+    mode: sandboxWorkspaceModeLabel(params.config),
+    taskId: sandboxTaskIdLabel(params.config)
+  });
   const selectedToolIds = new Set(tools.map((tool) => tool.id));
   const enforceCanonicalPlan = params.config.agentClientSource === 'canonical';
   const unexpectedCapabilityMounts = enforceCanonicalPlan
@@ -471,6 +564,8 @@ export function collectSandboxRecoverySnapshot(params: {
   const mountSnapshots = expectedMounts({
     config: params.config,
     branch: params.branch,
+    container: params.container,
+    workspace,
     tools,
     actualMounts: mountsByDestination
   }).map((expected) => {
@@ -510,7 +605,8 @@ export function collectSandboxRecoverySnapshot(params: {
   return {
     identityOk: typeof inspection.Id === 'string'
       && inspection.Id.length > 0
-      && branchLabel === params.branch,
+      && branchLabel === params.branch
+      && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
     runtimeCapabilityOk: enforceCanonicalPlan
       ? labels[sandboxRuntimeCapabilityLabel(params.config)] === capabilityPlan.runtimeSignature
       : undefined,
@@ -673,6 +769,7 @@ function assess(params: {
   config: SandboxConfig;
   engine: string;
   branch: string;
+  workspace?: SandboxWorkspaceIdentity;
   container: string;
   deps?: RecoveryCommandDeps;
 }): { snapshot: SandboxRecoverySnapshot; findings: SandboxRecoveryFinding[] } {
@@ -680,21 +777,64 @@ function assess(params: {
   return { snapshot, findings: classifySandboxRecovery(snapshot) };
 }
 
-export function assertFreshSandboxReady(params: {
+function canRetryFreshReadiness(findings: SandboxRecoveryFinding[]): boolean {
+  return findings.length > 0 && findings.every((finding) =>
+    finding.repairKind === 'hard-failure'
+    && finding.path !== undefined
+    && (
+      finding.path.startsWith('/workspace/.agents/workspace')
+      || finding.path === '/home/devuser/.host-shell-config'
+      || finding.path === '/home/devuser/.bash_aliases'
+    )
+  );
+}
+
+export async function assertFreshSandboxReady(params: {
   config: SandboxConfig;
   engine: string;
   branch: string;
+  workspace?: SandboxWorkspaceIdentity;
   container: string;
   copiedEntries: TmpfsSeedEntry[];
   deps?: RecoveryCommandDeps;
-}): void {
+}): Promise<void> {
   validateTmpfsSeedEntries({
     engine: params.engine,
     container: params.container,
     entries: params.copiedEntries,
     deps: params.deps
   });
-  const { findings } = assess(params);
+  let { findings } = assess(params);
+  if (canRetryFreshReadiness(findings)) {
+    const runVerboseFn = params.deps?.runVerbose ?? runVerboseEngine;
+    runVerboseFn(params.engine, 'docker', ['restart', params.container]);
+    prepareTmpfsMounts({
+      engine: params.engine,
+      container: params.container,
+      mountPaths: resolveTools(params.config)
+        .filter((tool) => tool.tmpfs)
+        .map((tool) => tool.containerMount),
+      deps: params.deps
+    });
+    hydrateTmpfsSeedEntries({
+      engine: params.engine,
+      container: params.container,
+      entries: params.copiedEntries,
+      replace: true,
+      deps: params.deps
+    });
+    let retried = assess(params);
+    if (!retried.findings.some((finding) => finding.repairKind === 'hard-failure')) {
+      repairFindings({
+        engine: params.engine,
+        container: params.container,
+        findings: retried.findings,
+        deps: params.deps
+      });
+      retried = assess(params);
+    }
+    findings = retried.findings;
+  }
   if (findings.length > 0) {
     throw new Error(`Fresh sandbox readiness check failed: ${describeFindings(findings)}`);
   }
@@ -705,6 +845,11 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
   const startFn = deps?.start ?? startSandboxContainer;
   const warnings: string[] = [];
   let failure: Error | null = null;
+  ensureSandboxControlBroker({
+    config: params.config,
+    container: params.row.name,
+    workspace: params.workspace ?? { mode: 'branch-only' }
+  });
 
   try {
     if (!params.row.running) {
@@ -713,6 +858,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
         config: params.config,
         engine: params.engine,
         branch: params.branch,
+        workspace: params.workspace,
         container: params.row.name,
         deps
       });
@@ -739,6 +885,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
         config: params.config,
         engine: params.engine,
         branch: params.branch,
+        workspace: params.workspace,
         container: params.row.name,
         deps
       });
@@ -753,6 +900,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
           config: params.config,
           engine: params.engine,
           branch: params.branch,
+          workspace: params.workspace,
           container: params.row.name,
           deps
         });
@@ -767,6 +915,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       config: params.config,
       engine: params.engine,
       branch: params.branch,
+      workspace: params.workspace,
       container: params.row.name,
       deps
     });
@@ -791,6 +940,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
         config: params.config,
         engine: params.engine,
         branch: params.branch,
+        workspace: params.workspace,
         container: params.row.name,
         deps
       });
@@ -811,6 +961,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       config: params.config,
       engine: params.engine,
       branch: params.branch,
+      workspace: params.workspace,
       container: params.row.name,
       deps
     });
@@ -831,6 +982,11 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
   const warning = `Sandbox recovery failed in place. Replacing only the container. ${dataBoundary}`;
   warnings.push(warning);
   (params.writeWarning ?? ((message) => process.stderr.write(`${message}\n`)))(warning);
+  const runVerboseFn = deps?.runVerbose ?? runVerboseEngine;
+  if (params.row.running) {
+    runVerboseFn(params.engine, 'docker', ['stop', params.row.name]);
+  }
+  runVerboseFn(params.engine, 'docker', ['rm', params.row.name]);
   await params.recreate(params.branch);
 
   const rows = (deps?.fetchRows ?? fetchSandboxRows)(
@@ -849,6 +1005,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     config: params.config,
     engine: params.engine,
     branch: params.branch,
+    workspace: params.workspace,
     container: replacement.name,
     deps
   });

package/lib/sandbox/redaction.ts

@@ -0,0 +1,14 @@
+const SENSITIVE_OUTPUT_PATTERNS = [
+  { pattern: /\{[^{}]*"claudeAiOauth"[\s\S]*?\}\s*\}/g, replacement: '[REDACTED credentials blob]' },
+  { pattern: /sk-ant-[A-Za-z0-9_-]{20,}/g, replacement: '[REDACTED claude token]' },
+  { pattern: /gh[psoru]_[A-Za-z0-9]{30,}/g, replacement: '[REDACTED github token]' },
+  { pattern: /Bearer\s+[A-Za-z0-9._~+/=-]{20,}/gi, replacement: 'Bearer [REDACTED]' }
+];
+
+export function redactCommandError(text: unknown): string {
+  if (!text || typeof text !== 'string') return '';
+  return SENSITIVE_OUTPUT_PATTERNS.reduce(
+    (result, { pattern, replacement }) => result.replace(pattern, replacement),
+    text
+  );
+}