@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/sandbox/engine.ts

@@ -18,10 +18,20 @@ const PLATFORM_DEFAULTS = Object.freeze({
   win32: ENGINES.WSL2
 });
 
+export type SandboxEngineInput = string | Record<string, string | null | undefined> | null | undefined;
+
 type EngineConfig = EffectiveSandboxConfig & {
-  engine?: string | null;
+  engine?: SandboxEngineInput;
 };
 
+function isPerPlatformEngine(engine: SandboxEngineInput): engine is Record<string, string | null | undefined> {
+  return typeof engine === 'object' && engine !== null;
+}
+
+function resolveEngineForPlatform(engine: SandboxEngineInput, os: string): string | null | undefined {
+  return isPerPlatformEngine(engine) ? engine[os] : engine;
+}
+
 type EngineDependencies = {
   platformFn?: typeof platform;
   runFn?: RunFns['run'];
@@ -83,33 +93,34 @@ function ensureBuildKit(engine: string, runOkEngineFn: typeof runOkEngine): void
 }
 
 export function validateSandboxEngine(
-  engine: string | null | undefined,
+  engine: SandboxEngineInput,
   { platformFn = platform }: Pick<EngineDependencies, 'platformFn'> = {}
 ): string | null {
-  if (engine === null || engine === undefined) {
+  const os = platformFn();
+  const resolved = resolveEngineForPlatform(engine, os);
+  if (resolved === null || resolved === undefined) {
     return null;
   }
 
-  const os = platformFn();
-  if (!(engine in ADAPTERS)) {
+  if (!(resolved in ADAPTERS)) {
     const known = Object.keys(ADAPTERS).join(', ');
     throw new Error(
-      `sandbox: invalid "sandbox.engine" value "${engine}" (unknown sandbox engine). `
+      `sandbox: invalid "sandbox.engine" value "${resolved}" (unknown sandbox engine). `
       + `Valid engines: ${known}.`
     );
   }
 
-  const adapter = ADAPTERS[engine as keyof typeof ADAPTERS];
+  const adapter = ADAPTERS[resolved as keyof typeof ADAPTERS];
   if (!adapter.supportedPlatforms.includes(os)) {
     const supported = enginesForPlatform(os);
     const supportedList = supported.length > 0 ? supported.join(', ') : 'none';
     throw new Error(
-      `sandbox: "sandbox.engine" value "${engine}" is not supported on ${os}. `
+      `sandbox: "sandbox.engine" value "${resolved}" is not supported on ${os}. `
       + `Supported engines on ${os}: ${supportedList}.`
     );
   }
 
-  return engine;
+  return resolved;
 }
 
 export function detectEngine(

package/lib/sandbox/mounts.ts

@@ -26,6 +26,7 @@ export function sandboxCoreBindMounts(
     workspaceViewRoot: string;
     controlDir: string;
     controlStatusDir: string;
+    runtimeDir?: string;
     taskSource?: string;
     taskId?: string;
   }
@@ -89,5 +90,12 @@ export function sandboxCoreBindMounts(
     containerPath: '/run/agent-infra/control',
     readOnly: false
   });
+  if (taskBound && overrides.runtimeDir) {
+    mounts.push({
+      hostPaths: [overrides.runtimeDir],
+      containerPath: '/run/agent-infra/runtime',
+      readOnly: false
+    });
+  }
   return mounts;
 }

package/lib/sandbox/recovery.ts

@@ -35,7 +35,7 @@ import {
   type SandboxWorkspaceIdentity
 } from './workspace-identity.ts';
 import { inspectWorktree, type WorktreeSnapshot } from './worktree-safety.ts';
-import { runEngine, runOkEngine, runVerboseEngine } from './shell.ts';
+import { commandForEngine, runEngine, runOkEngine, runProbe, runVerboseEngine } from './shell.ts';
 import {
   declaredTmpfsSeedEntries,
   resolveTools,
@@ -49,15 +49,19 @@ import {
   startSandboxContainer,
   type SandboxRow
 } from './commands/list-running.ts';
-import { getProcessStartTime, processIdentityMatches, removePidFileIfMatches } from '../server/process-state.ts';
+import { getProcessIdentityState, getProcessStartTime, removePidFileIfMatches } from '../server/process-state.ts';
 import {
   acquireSandboxControlBrokerStartup,
-  isSandboxControlRootQuiescing
+  garbageCollectSandboxControlRoot,
+  isSandboxControlRootQuiescing,
+  readSandboxControlManifest,
+  type BrokerOwner
 } from './control/lifecycle.ts';
 import {
   appendSandboxControlAudit,
   readSandboxControlStatus
 } from './control/state.ts';
+import { inspectSandboxControlContainer } from './control/container-identity.ts';
 import {
   SANDBOX_CONTROL_FUTURE_SKEW_MS,
   SANDBOX_CONTROL_STATUS_STALE_MS,
@@ -89,6 +93,9 @@ export type SandboxRecoverySnapshot = {
   actualBranch: string | null;
   expectedWorkspace: SandboxWorkspaceIdentity;
   actualWorkspace: SandboxContainerWorkspaceIdentity;
+  workspaceTopology?: 'legacy-parent' | 'per-state' | 'unknown';
+  taskView?: { path: string; readable: boolean };
+  runtimeStoreOk?: boolean;
   runtimeCapabilityOk?: boolean;
   unexpectedCapabilityMounts?: string[];
   mounts: Array<{
@@ -142,8 +149,27 @@ type RecoveryCommandDeps = {
   start?: typeof startSandboxContainer;
   fetchRows?: typeof fetchSandboxRows;
   ensureControlBroker?: () => void | Promise<void>;
+  probe?: typeof runProbe;
 };
 
+export function worktreeProbeForEngine(
+  engine: string,
+  probe: typeof runProbe = runProbe
+): typeof runProbe {
+  return (cmd, args, opts = {}) => {
+    const engineArgs = [...args];
+    if (engine === 'wsl2' && cmd === 'git') {
+      for (let index = 0; index < engineArgs.length - 1; index += 1) {
+        if (engineArgs[index] === '-C') {
+          engineArgs[index + 1] = toEnginePath(engine, engineArgs[index + 1]!);
+        }
+      }
+    }
+    const command = commandForEngine(engine, cmd, engineArgs);
+    return probe(command.cmd, command.args, opts);
+  };
+}
+
 type EnsureSandboxReadyParams = {
   config: SandboxConfig;
   engine: string;
@@ -151,6 +177,7 @@ type EnsureSandboxReadyParams = {
   workspace?: SandboxWorkspaceIdentity;
   row: SandboxRow;
   allowRecreate?: boolean;
+  forceRecreate?: boolean;
   recreate?: (branch: string) => Promise<void>;
   writeWarning?: (message: string) => void;
   deps?: RecoveryCommandDeps;
@@ -168,7 +195,7 @@ async function waitForSandboxControlBrokerStatus(params: {
   statusDir: string;
   generation: string;
   pid: number;
-  startTime?: string;
+  startTime?: number;
 }, timeoutMs = 5_000): Promise<void> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -191,7 +218,7 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
   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 manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as SandboxControlManifest;
+  const manifest = readSandboxControlManifest(manifestPath);
   const root = path.dirname(manifestPath);
   if (isSandboxControlRootQuiescing(root)) throw new Error('SANDBOX_CONTROL_QUIESCING');
   const brokerPath = path.join(root, 'broker.json');
@@ -207,6 +234,7 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
       version?: unknown;
       pid?: unknown;
       startTime?: unknown;
+      brokerId?: unknown;
       token?: unknown;
       generation?: unknown;
     };
@@ -216,15 +244,24 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
     } catch {
       // Malformed owner records are stale and replaced below.
     }
-    const owner = broker !== null && typeof broker.pid === 'number' && typeof broker.startTime === 'string'
-      ? { version: 1 as const, pid: broker.pid, startTime: broker.startTime }
+    const owner = broker !== null && broker.version === 3 && typeof broker.pid === 'number'
+      && Number.isSafeInteger(broker.pid) && broker.pid > 0 && typeof broker.startTime === 'number'
+      && Number.isSafeInteger(broker.startTime) && typeof broker.brokerId === 'string'
+      && broker.brokerId.length > 0 && typeof broker.token === 'string'
+      && typeof broker.generation === 'string'
+      ? broker as BrokerOwner
       : null;
-    const live = owner !== null && processIdentityMatches(owner);
+    if (broker === null || broker.version !== 3 || owner === null) {
+      throw new Error('SANDBOX_CONTROL_BROKER_VERSION_INVALID: rebuild the sandbox container before starting a new broker');
+    }
+    const ownerState = getProcessIdentityState({ pid: owner.pid, startTime: owner.startTime });
+    if (ownerState === 'unknown') throw new Error('SANDBOX_CONTROL_BROKER_OWNER_UNAVAILABLE');
+    const live = ownerState === 'alive';
     if (
       live
       && owner !== null
       && broker !== null
-      && broker.version === 2
+      && broker.version === 3
       && broker.token === manifest.token
       && broker.generation === manifest.generation
     ) {
@@ -237,27 +274,6 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
       });
       return;
     }
-    if (live && owner) {
-      const deadline = Date.now() + 5_000;
-      while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, 25));
-        try {
-          if (fs.readFileSync(brokerPath, 'utf8') !== brokerSnapshot) {
-            return startSandboxControlBroker(repoRoot, manifestPath);
-          }
-        } catch (error) {
-          if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-            return startSandboxControlBroker(repoRoot, manifestPath);
-          }
-          throw error;
-        }
-        if (!processIdentityMatches(owner)) {
-          removePidFileIfMatches(brokerPath, brokerSnapshot);
-          return startSandboxControlBroker(repoRoot, manifestPath);
-        }
-      }
-      throw new Error('SANDBOX_CONTROL_BROKER_OWNER_ACTIVE');
-    }
   }
   const startupStartTime = getProcessStartTime(process.pid);
   if (!startupStartTime) throw new Error('SANDBOX_CONTROL_BROKER_IDENTITY_UNAVAILABLE');
@@ -317,9 +333,16 @@ async function ensureSandboxControlBroker(params: {
     identity: params.workspace
   });
   if (!fs.existsSync(control.manifestPath)) return;
-  const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8')) as SandboxControlManifest;
-  if (manifest.version !== 3) {
-    throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 3; container-only recreation is required');
+  const validatedManifest = readSandboxControlManifest(control.manifestPath);
+  const containerObservation = await inspectSandboxControlContainer(validatedManifest);
+  if (containerObservation.state === 'unknown') {
+    throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${containerObservation.reason}`);
+  }
+  if (containerObservation.state === 'absent') {
+    await garbageCollectSandboxControlRoot(control.root, {
+      inspectContainer: (timeoutMs) => inspectSandboxControlContainer(validatedManifest, { timeoutMs })
+    });
+    throw new Error('SANDBOX_CONTROL_CONTAINER_ABSENT: recreate the sandbox container before broker recovery');
   }
   const brokerPath = path.join(control.root, 'broker.json');
   try {
@@ -327,20 +350,33 @@ async function ensureSandboxControlBroker(params: {
       version?: unknown;
       pid?: unknown;
       startTime?: unknown;
+      brokerId?: unknown;
       token?: unknown;
       generation?: unknown;
     };
+    const validIdentity = typeof broker.pid === 'number'
+      && Number.isSafeInteger(broker.pid)
+      && typeof broker.startTime === 'number'
+      && Number.isSafeInteger(broker.startTime);
+    const ownerState = validIdentity
+      ? getProcessIdentityState({ pid: broker.pid as number, startTime: broker.startTime as number })
+      : 'dead';
+    if (ownerState === 'unknown') throw new Error('SANDBOX_CONTROL_BROKER_OWNER_UNAVAILABLE');
     if (
-      broker.version === 2
+      broker.version === 3
       && typeof broker.pid === 'number'
-      && typeof broker.startTime === 'string'
-      && broker.token === manifest.token
-      && broker.generation === manifest.generation
-      && processIdentityMatches({ version: 1, pid: broker.pid, startTime: broker.startTime })
+      && Number.isSafeInteger(broker.pid)
+      && typeof broker.startTime === 'number'
+      && Number.isSafeInteger(broker.startTime)
+      && typeof broker.brokerId === 'string'
+      && broker.brokerId.length > 0
+      && broker.token === validatedManifest.token
+      && broker.generation === validatedManifest.generation
+      && ownerState === 'alive'
     ) {
       try {
         const status = readSandboxControlStatus(control.statusDir);
-        if (status.generation === manifest.generation && status.broker.pid === broker.pid
+        if (status.generation === validatedManifest.generation && status.broker.pid === broker.pid
           && status.broker.startTime === broker.startTime
           && Date.now() - status.updatedAt <= SANDBOX_CONTROL_STATUS_STALE_MS
           && status.updatedAt <= Date.now() + SANDBOX_CONTROL_FUTURE_SKEW_MS) return;
@@ -350,13 +386,14 @@ async function ensureSandboxControlBroker(params: {
       await waitForSandboxControlBrokerStatus({
         root: control.root,
         statusDir: control.statusDir,
-        generation: manifest.generation,
+        generation: validatedManifest.generation,
         pid: broker.pid,
         startTime: broker.startTime
       });
       return;
     }
-  } catch {
+  } catch (error) {
+    if (error instanceof Error && error.message === 'SANDBOX_CONTROL_BROKER_OWNER_UNAVAILABLE') throw error;
     // A missing, stale, or malformed broker record is replaced below.
   }
   await startSandboxControlBroker(params.config.repoRoot, control.manifestPath);
@@ -393,6 +430,30 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
       message: 'Container runtime capability signature does not match the current sandbox plan.'
     });
   }
+  if (snapshot.workspaceTopology === 'legacy-parent') {
+    findings.push({
+      repairKind: 'hard-failure',
+      code: 'SANDBOX_WORKSPACE_TOPOLOGY_MISMATCH',
+      message: 'Sandbox uses the legacy workspace parent-mount topology; recreate the container explicitly to migrate it.',
+      path: '/workspace/.agents/workspace'
+    });
+  }
+  if (snapshot.taskView && !snapshot.taskView.readable) {
+    findings.push({
+      repairKind: 'hard-failure',
+      code: 'SANDBOX_TASK_VIEW_UNREADABLE',
+      message: `Bound task view is not readable at ${snapshot.taskView.path}.`,
+      path: snapshot.taskView.path
+    });
+  }
+  if (snapshot.runtimeStoreOk === false) {
+    findings.push({
+      repairKind: 'hard-failure',
+      code: 'SANDBOX_RUNTIME_STORE_UNAVAILABLE',
+      message: 'Task-bound runtime store is not writable and readable by devuser.',
+      path: '/run/agent-infra/runtime'
+    });
+  }
   for (const mountPath of snapshot.unexpectedCapabilityMounts ?? []) {
     findings.push({
       repairKind: 'hard-failure',
@@ -402,6 +463,10 @@ export function classifySandboxRecovery(snapshot: SandboxRecoverySnapshot): Sand
   }
 
   for (const mount of snapshot.mounts) {
+    if (
+      snapshot.workspaceTopology === 'legacy-parent'
+      && mount.path.startsWith('/workspace/.agents/workspace')
+    ) continue;
     if (
       mount.actualType !== mount.expectedType
       || !mount.sourceMatches
@@ -494,6 +559,20 @@ function inspectContainer(
   return parsed[0] as DockerInspection;
 }
 
+function workspaceTopology(mountsByDestination: ReadonlyMap<string, DockerMount>): SandboxRecoverySnapshot['workspaceTopology'] {
+  if (mountsByDestination.has('/workspace/.agents/workspace')) return 'legacy-parent';
+  const perState = [
+    '/workspace/.agents/workspace/active',
+    '/workspace/.agents/workspace/active/.short-ids.json',
+    '/workspace/.agents/workspace/completed',
+    '/workspace/.agents/workspace/blocked',
+    '/workspace/.agents/workspace/archive'
+  ];
+  return perState.some((destination) => mountsByDestination.has(destination))
+    ? 'per-state'
+    : 'unknown';
+}
+
 function probe(
   engine: string,
   container: string,
@@ -573,6 +652,7 @@ function expectedMounts(params: {
     controlStatusDir: control.statusDir,
     ...(params.workspace.mode === 'task-bound'
       ? {
+        runtimeDir: control.runtimeDir,
         taskSource: assertSandboxTaskSource(config.repoRoot, params.workspace.taskId),
         taskId: params.workspace.taskId
       }
@@ -706,6 +786,10 @@ export function collectSandboxRecoverySnapshot(params: {
   const capabilityPlan = createSandboxCapabilityPlan(params.config);
   const workspace = params.workspace ?? { mode: 'branch-only' as const };
   const tools = [...capabilityPlan.tools];
+  const topology = workspaceTopology(mountsByDestination);
+  const taskViewPath = workspace.mode === 'task-bound'
+    ? `/workspace/.agents/workspace/active/${workspace.taskId}/task.md`
+    : null;
   const seeds = declaredTmpfsSeedEntries(tools).map((seed) => {
     const mounted = mountsByDestination.get(seed.stagingPath)?.Type === 'bind';
     return {
@@ -736,6 +820,15 @@ export function collectSandboxRecoverySnapshot(params: {
       runOkFn
     )
   }));
+  const runtimeStoreOk = workspace.mode === 'task-bound'
+    ? probe(
+      params.engine,
+      params.container,
+      'probe="$1/.agent-infra-runtime-$$"; trap \'rm -f -- "$probe"\' EXIT; printf runtime-probe > "$probe" && test "$(cat -- "$probe")" = runtime-probe',
+      ['/run/agent-infra/runtime'],
+      runOkFn
+    )
+    : undefined;
   const labels = inspection.Config?.Labels ?? {};
   const branchLabel = labels[sandboxBranchLabel(params.config)];
   const containerWorkspace = parseSandboxWorkspaceIdentity(labels, {
@@ -797,6 +890,20 @@ export function collectSandboxRecoverySnapshot(params: {
     actualBranch: typeof branchLabel === 'string' ? branchLabel : null,
     expectedWorkspace: workspace,
     actualWorkspace: containerWorkspace,
+    workspaceTopology: topology,
+    ...(taskViewPath === null ? {} : {
+      taskView: {
+        path: taskViewPath,
+        readable: probe(
+          params.engine,
+          params.container,
+          'test -r "$1"',
+          [taskViewPath],
+          runOkFn
+        )
+      }
+    }),
+    ...(runtimeStoreOk === undefined ? {} : { runtimeStoreOk }),
     identityOk: typeof inspection.Id === 'string' && inspection.Id.length > 0
       && branchLabel === params.branch
       && sameSandboxWorkspaceIdentity(containerWorkspace, workspace),
@@ -973,11 +1080,13 @@ function assess(params: {
 function canRetryFreshReadiness(findings: SandboxRecoveryFinding[]): boolean {
   return findings.length > 0 && findings.every((finding) =>
     finding.repairKind === 'hard-failure'
+    && finding.code !== 'SANDBOX_WORKSPACE_TOPOLOGY_MISMATCH'
     && finding.path !== undefined
     && (
       finding.path.startsWith('/workspace/.agents/workspace')
       || finding.path === '/home/devuser/.host-shell-config'
       || finding.path === '/home/devuser/.bash_aliases'
+      || finding.path === '/run/agent-infra/runtime'
     )
   );
 }
@@ -1048,6 +1157,9 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
         workspace: params.workspace ?? { mode: 'branch-only' }
       });
     }
+    if (params.forceRecreate) {
+      throw new Error('Explicit container recreation requested.');
+    }
     if (!params.row.running) {
       startFn(params.engine, params.row.name);
       const initial = assess({
@@ -1192,7 +1304,8 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       `SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: expected exactly one existing worktree for '${params.branch}', found ${existingWorktrees.length}. ${remediation}`
     );
   }
-  const beforeInspection = inspectWorktree(existingWorktrees[0]!);
+  const worktreeProbe = worktreeProbeForEngine(params.engine, deps?.probe);
+  const beforeInspection = inspectWorktree(existingWorktrees[0]!, { probe: worktreeProbe });
   if (beforeInspection.status === 'failed') {
     throw new Error(`SANDBOX_RECOVERY_WORKTREE_SNAPSHOT_INVALID: ${beforeInspection.message}`);
   }
@@ -1204,17 +1317,14 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     );
   }
 
-  const warning = `Sandbox recovery failed in place. Replacing only the container. ${dataBoundary}`;
+  const warning = params.forceRecreate
+    ? `Explicit sandbox recreation requested. Replacing only the container. ${dataBoundary}`
+    : `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;
   let replacementResult: SandboxReadyResult | null = null;
   let replacementFailure: unknown = null;
   try {
-    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)(
@@ -1245,7 +1355,7 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     replacementFailure = error;
   }
 
-  const afterInspection = inspectWorktree(before.worktree);
+  const afterInspection = inspectWorktree(before.worktree, { probe: worktreeProbe });
   if (afterInspection.status === 'failed' || afterInspection.snapshot.identity !== before.identity) {
     const detail = afterInspection.status === 'failed'
       ? afterInspection.message

package/lib/sandbox/workspace-view.ts

@@ -47,8 +47,10 @@ export function sandboxWorkspaceViewPaths(params: Readonly<{
 }
 
 export type SandboxControlSetup = Readonly<{
+  root: string;
   channelDir: string;
   statusDir: string;
+  runtimeDir: string;
   manifestPath: string;
   token: string;
   generation: string;
@@ -59,7 +61,7 @@ export function sandboxControlPaths(params: Readonly<{
   project: string;
   container: string;
   identity: SandboxWorkspaceIdentity;
-}>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; manifestPath: string }> {
+}>): Readonly<{ root: string; channelDir: string; statusDir: string; processingDir: string; runtimeDir: string; manifestPath: string }> {
   const identityKey = params.identity.mode === 'task-bound'
     ? `task-bound:${params.identity.taskId}`
     : 'branch-only';
@@ -70,6 +72,7 @@ export function sandboxControlPaths(params: Readonly<{
     channelDir: path.join(root, 'channel'),
     statusDir: path.join(root, 'public'),
     processingDir: path.join(root, 'processing'),
+    runtimeDir: path.join(root, 'runtime'),
     manifestPath: path.join(root, 'manifest.json')
   };
 }
@@ -84,7 +87,11 @@ function assertSafeDirectory(directory: string, expectedBase: string): void {
   }
 }
 
-function assertSafeMountTargetPath(target: string, worktreeRoot: string, canonicalWorktreeRoot: string): void {
+function assertSafeMountTargetPath(
+  target: string,
+  worktreeRoot: string,
+  canonicalWorktreeRoot: string
+): void {
   const relative = path.relative(worktreeRoot, target);
   if (relative.startsWith('..') || path.isAbsolute(relative)) {
     throw new Error(`Sandbox workspace mount target escapes its worktree: ${target}`);
@@ -106,6 +113,21 @@ function assertSafeMountTargetPath(target: string, worktreeRoot: string, canonic
   }
 }
 
+export function assertSandboxTaskSource(repoRoot: string, taskId: string): string {
+  if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
+  const activeRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'active'));
+  const source = path.join(activeRoot, taskId);
+  const stat = fs.lstatSync(source);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} must be a real directory`);
+  }
+  const canonical = fs.realpathSync.native(source);
+  if (path.dirname(canonical) !== activeRoot) {
+    throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} escapes the active workspace`);
+  }
+  return canonical;
+}
+
 export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string): void {
   const resolvedWorktreeRoot = path.resolve(worktreeRoot);
   const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
@@ -118,25 +140,12 @@ export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string): void
   fs.mkdirSync(workspaceRoot, { recursive: true, mode: 0o700 });
   for (const { hostPath } of statePaths) {
     fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
+    fs.chmodSync(hostPath, 0o700);
   }
+  fs.chmodSync(workspaceRoot, 0o700);
   fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
 }
 
-export function assertSandboxTaskSource(repoRoot: string, taskId: string): string {
-  if (!/^TASK-\d{8}-\d{6}$/.test(taskId)) throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-  const activeRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'active'));
-  const source = path.join(activeRoot, taskId);
-  const stat = fs.lstatSync(source);
-  if (!stat.isDirectory() || stat.isSymbolicLink()) {
-    throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} must be a real directory`);
-  }
-  const canonical = fs.realpathSync.native(source);
-  if (path.dirname(canonical) !== activeRoot) {
-    throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} escapes the active workspace`);
-  }
-  return canonical;
-}
-
 export function materializeSandboxWorkspaceView(params: Readonly<{
   base: string;
   project: string;
@@ -180,17 +189,38 @@ export function materializeSandboxControl(params: Readonly<{
   container: string;
   branch: string;
   identity: SandboxWorkspaceIdentity;
+  engine?: string;
+  replacementLease?: Readonly<{
+    root: string;
+    assertOwned(): void;
+  }>;
 }>): SandboxControlSetup {
-  const { root, channelDir, statusDir, processingDir, manifestPath } = sandboxControlPaths(params);
+  const { root, channelDir, statusDir, processingDir, runtimeDir, manifestPath } = sandboxControlPaths(params);
   assertSafeDirectory(root, path.resolve(params.base));
+  if (fs.existsSync(root)) {
+    if (!params.replacementLease || path.resolve(params.replacementLease.root) !== root) {
+      throw new Error('SANDBOX_CONTROL_REPLACEMENT_REQUIRED');
+    }
+    params.replacementLease.assertOwned();
+  }
   const consumedDir = path.join(root, 'consumed');
   assertSafeDirectory(consumedDir, root);
   fs.rmSync(consumedDir, { recursive: true, force: true });
   fs.mkdirSync(consumedDir, { recursive: true, mode: 0o700 });
-  for (const directory of [statusDir, processingDir]) {
+  for (const directory of [statusDir, processingDir, runtimeDir]) {
     assertSafeDirectory(directory, root);
+    if (directory === runtimeDir) fs.rmSync(directory, { recursive: true, force: true });
     fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
   }
+  for (const directory of [
+    path.join(runtimeDir, 'clients'),
+    path.join(runtimeDir, 'clients', 'codex', 'capabilities'),
+    path.join(runtimeDir, 'clients', 'codex', 'lifecycle')
+  ]) {
+    assertSafeDirectory(directory, runtimeDir);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    fs.chmodSync(directory, 0o700);
+  }
   for (const queue of ['requests', 'responses']) {
     const directory = path.join(channelDir, queue);
     assertSafeDirectory(directory, root);
@@ -201,11 +231,13 @@ export function materializeSandboxControl(params: Readonly<{
   const generation = randomBytes(16).toString('hex');
   const repoRoot = fs.realpathSync.native(params.repoRoot);
   const manifest: SandboxControlManifest = {
-    version: 3,
+    version: 5,
+    engine: params.engine ?? 'docker',
     repoRoot,
     worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
     project: params.project,
     container: params.container,
+    containerIdentity: { id: '', labels: {} },
     branch: params.branch,
     mode: params.identity.mode,
     taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
@@ -213,8 +245,27 @@ export function materializeSandboxControl(params: Readonly<{
     generation,
     channelDir,
     publicStatusDir: statusDir,
-    processingDir
+    processingDir,
+    runtimeDir
   };
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-  return { channelDir, statusDir, manifestPath, token, generation };
+  return { root, channelDir, statusDir, runtimeDir, manifestPath, token, generation };
+}
+
+export function finalizeSandboxControlManifest(
+  setup: SandboxControlSetup,
+  identity: Readonly<{ engine: string; id: string; labels: Readonly<Record<string, string>> }>
+): void {
+  if (!identity.engine || !identity.id) throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
+  const manifest = JSON.parse(fs.readFileSync(setup.manifestPath, 'utf8')) as Record<string, unknown>;
+  manifest.version = 5;
+  manifest.engine = identity.engine;
+  manifest.containerIdentity = { id: identity.id, labels: { ...identity.labels } };
+  const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(manifest)}\n`, { mode: 0o600, flag: 'wx' });
+    fs.renameSync(temporary, setup.manifestPath);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
 }