@fitlab-ai/agent-infra 0.9.7 → 0.9.8

package/lib/sandbox/control/protocol.ts

@@ -27,12 +27,15 @@ export type SandboxControlContainerIdentity = Readonly<{
   id: string;
   labels: Readonly<Record<string, string>>;
 }>;
-export type SandboxControlManifest = Readonly<{
-  version: 4; engine: string; repoRoot: string; worktreeRoot: string; project: string; container: string;
+export type SandboxControlManifestBase = Readonly<{
+  engine: string; repoRoot: string; worktreeRoot: string; project: string; container: string;
   containerIdentity: SandboxControlContainerIdentity;
   branch: string; mode: 'task-bound' | 'branch-only'; taskId: string | null; token: string;
   generation: string; channelDir: string; publicStatusDir: string; processingDir: string;
 }>;
+export type SandboxControlLegacyManifest = SandboxControlManifestBase & Readonly<{ version: 4 }>;
+export type SandboxControlManifest = SandboxControlManifestBase & Readonly<{ version: 5; runtimeDir: string }>;
+export type SandboxControlManifestLike = SandboxControlLegacyManifest | SandboxControlManifest;
 export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
   version: 3;
   brokerId: string;

package/lib/sandbox/control/state.ts

@@ -3,12 +3,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { buildProcessTreeStopCommand } from '../../server/process-control.ts';
-import { processIdentityMatches } from '../../server/process-state.ts';
-import type { ProcessIdentity } from '../../server/process-state.ts';
+import { getProcessIdentityState } from '../../server/process-state.ts';
+import type { ProcessIdentity, ProcessIdentityProbe } from '../../server/process-state.ts';
 import type {
   SandboxControlExecution,
   SandboxControlLease,
-  SandboxControlManifest,
+  SandboxControlManifestLike,
   SandboxControlStatus
 } from './protocol.ts';
 
@@ -36,12 +36,12 @@ export function readJsonFile(filePath: string): unknown {
   return JSON.parse(fs.readFileSync(filePath, 'utf8'));
 }
 
-export function statusPath(manifest: SandboxControlManifest): string {
+export function statusPath(manifest: SandboxControlManifestLike): string {
   return path.join(manifest.publicStatusDir, 'status.json');
 }
 
 export function writeSandboxControlStatus(
-  manifest: SandboxControlManifest,
+  manifest: SandboxControlManifestLike,
   broker: ProcessIdentity & { brokerId: string },
   state: SandboxControlStatus['state'],
   reasonCode: string | null,
@@ -72,7 +72,7 @@ export function readSandboxControlStatus(directory: string): SandboxControlStatu
   return parseSandboxControlStatus(readJsonFile(path.join(directory, 'status.json')));
 }
 
-export function readActiveLease(manifest: SandboxControlManifest, now = Date.now()): SandboxControlLease | null {
+export function readActiveLease(manifest: SandboxControlManifestLike, now = Date.now()): SandboxControlLease | null {
   const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
   if (!fs.existsSync(filePath)) return null;
   const lease = readJsonFile(filePath) as Partial<SandboxControlLease> | null;
@@ -90,7 +90,11 @@ export function readActiveLease(manifest: SandboxControlManifest, now = Date.now
   return lease as SandboxControlLease;
 }
 
-export function cleanupStaleSandboxControlLease(manifest: SandboxControlManifest, now = Date.now()): boolean {
+export function cleanupStaleSandboxControlLease(
+  manifest: SandboxControlManifestLike,
+  now = Date.now(),
+  options: Readonly<{ identityProbe?: ProcessIdentityProbe }> = {}
+): boolean {
   const filePath = path.join(path.dirname(manifest.publicStatusDir), 'lease.json');
   if (!fs.existsSync(filePath)) return false;
   const raw = fs.readFileSync(filePath, 'utf8');
@@ -104,10 +108,12 @@ export function cleanupStaleSandboxControlLease(manifest: SandboxControlManifest
     || typeof lease.branch !== 'string' || typeof lease.reason !== 'string') {
     throw new Error('SANDBOX_CONTROL_LEASE_INVALID');
   }
-  const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
-    || lease.branch !== manifest.branch || lease.expiresAt! <= now || !processIdentityMatches({
+  const ownerState = (options.identityProbe ?? getProcessIdentityState)({
     pid: lease.owner.pid!, startTime: lease.owner.startTime!
   });
+  if (ownerState === 'unknown') throw new Error('SANDBOX_CONTROL_LEASE_OWNER_UNAVAILABLE');
+  const stale = lease.generation !== manifest.generation || lease.taskId !== manifest.taskId
+    || lease.branch !== manifest.branch || lease.expiresAt! <= now || ownerState === 'dead';
   if (!stale) return false;
   if (fs.readFileSync(filePath, 'utf8') !== raw) throw new Error('SANDBOX_CONTROL_LEASE_OWNERSHIP_LOST');
   fs.unlinkSync(filePath);
@@ -115,7 +121,7 @@ export function cleanupStaleSandboxControlLease(manifest: SandboxControlManifest
 }
 
 export function appendSandboxControlAudit(
-  manifest: SandboxControlManifest,
+  manifest: SandboxControlManifestLike,
   event: string,
   fields: Record<string, string | number | boolean | null> = {},
   now = Date.now()
@@ -130,7 +136,7 @@ export function appendSandboxControlAudit(
   });
 }
 
-export function executionPath(manifest: SandboxControlManifest, requestId: string): string {
+export function executionPath(manifest: SandboxControlManifestLike, requestId: string): string {
   return path.join(manifest.processingDir, requestId, 'execution.json');
 }
 
@@ -153,31 +159,42 @@ export function terminateSandboxControlExecution(
     deadlineAt?: number;
     forceAt?: number;
     allowForce?: boolean;
+    identityProbe?: ProcessIdentityProbe;
   } = {}
 ): boolean {
   const platform = options.platform ?? process.platform;
   const processGroupId = execution.child.processGroupId;
-  const processGroupAlive = (groupId: number): boolean => {
+  const processGroupState = (groupId: number): 'alive' | 'dead' | 'unknown' => {
     try {
       const rows = execFileSync('ps', ['-axo', 'pgid=,stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
       return rows.split('\n').some((row) => {
         const match = row.trim().match(/^(\d+)\s+(\S+)/);
         return Number(match?.[1]) === groupId && !match?.[2]?.startsWith('Z');
-      });
+      }) ? 'alive' : 'dead';
     } catch {
       try {
         process.kill(-groupId, 0);
-        return true;
+        return 'alive';
       } catch (error) {
-        return (error as NodeJS.ErrnoException).code === 'EPERM';
+        const code = (error as NodeJS.ErrnoException).code;
+        if (code === 'ESRCH') return 'dead';
+        if (code === 'EPERM') return 'alive';
+        return 'unknown';
       }
     }
   };
-  const treeAlive = (): boolean => {
+  const treeState = (): 'alive' | 'dead' | 'unknown' => {
     if (platform === 'win32' || !processGroupId) {
-      return processIdentityMatches({ pid: execution.child.pid, startTime: execution.child.startTime });
+      return (options.identityProbe ?? getProcessIdentityState)({
+        pid: execution.child.pid, startTime: execution.child.startTime
+      });
     }
-    return processGroupAlive(processGroupId);
+    return processGroupState(processGroupId);
+  };
+  const treeAlive = (): boolean => {
+    const state = treeState();
+    if (state === 'unknown') throw new Error('SANDBOX_CONTROL_EXECUTION_OWNER_UNAVAILABLE');
+    return state === 'alive';
   };
   if (!treeAlive()) return true;
   const command = buildProcessTreeStopCommand(processGroupId ?? execution.child.pid, platform);

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

@@ -6,6 +6,7 @@ import {
   worktreeDirCandidates
 } from './constants.ts';
 import type { SandboxConfig } from './config.ts';
+import { sandboxWorkspaceViewStatePaths } from './workspace-view.ts';
 
 export type SandboxBindMountDeclaration = {
   hostPaths: string[];
@@ -25,11 +26,25 @@ export function sandboxCoreBindMounts(
     workspaceViewRoot: string;
     controlDir: string;
     controlStatusDir: string;
+    runtimeDir?: string;
     taskSource?: string;
     taskId?: string;
   }
 ): SandboxBindMountDeclaration[] {
   const taskBound = Boolean(overrides.taskSource && overrides.taskId);
+  const workspaceMounts = sandboxWorkspaceViewStatePaths(overrides.workspaceViewRoot).map(
+    ({ state, hostPath }) => taskBound && state === 'active'
+      ? {
+          hostPaths: [path.join(hostPath, '.short-ids.json')],
+          containerPath: '/workspace/.agents/workspace/active/.short-ids.json',
+          readOnly: true
+        }
+      : {
+          hostPaths: [hostPath],
+          containerPath: path.posix.join('/workspace/.agents/workspace', state),
+          readOnly: true
+        }
+  );
   const mounts: SandboxBindMountDeclaration[] = [
     {
       hostPaths: overrides.worktree
@@ -38,11 +53,7 @@ export function sandboxCoreBindMounts(
       containerPath: '/workspace',
       readOnly: false
     },
-    {
-      hostPaths: [overrides.workspaceViewRoot],
-      containerPath: '/workspace/.agents/workspace',
-      readOnly: true
-    },
+    ...workspaceMounts,
   ];
   if (taskBound) {
     mounts.push({
@@ -79,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

@@ -49,7 +49,7 @@ 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,
   garbageCollectSandboxControlRoot,
@@ -93,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<{
@@ -251,7 +254,9 @@ export async function startSandboxControlBroker(repoRoot: string, manifestPath:
     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 live = owner !== null && processIdentityMatches({ pid: owner.pid, startTime: owner.startTime });
+    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
@@ -349,6 +354,14 @@ async function ensureSandboxControlBroker(params: {
       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 === 3
       && typeof broker.pid === 'number'
@@ -359,7 +372,7 @@ async function ensureSandboxControlBroker(params: {
       && broker.brokerId.length > 0
       && broker.token === validatedManifest.token
       && broker.generation === validatedManifest.generation
-      && processIdentityMatches({ pid: broker.pid, startTime: broker.startTime })
+      && ownerState === 'alive'
     ) {
       try {
         const status = readSandboxControlStatus(control.statusDir);
@@ -379,7 +392,8 @@ async function ensureSandboxControlBroker(params: {
       });
       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);
@@ -416,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',
@@ -425,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
@@ -517,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,
@@ -596,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
       }
@@ -729,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 {
@@ -759,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, {
@@ -820,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),
@@ -996,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'
     )
   );
 }
@@ -1236,14 +1322,9 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
     : `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)(

package/lib/sandbox/workspace-view.ts

@@ -50,6 +50,7 @@ export type SandboxControlSetup = Readonly<{
   root: string;
   channelDir: string;
   statusDir: string;
+  runtimeDir: string;
   manifestPath: string;
   token: string;
   generation: string;
@@ -60,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';
@@ -71,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')
   };
 }
@@ -85,6 +87,32 @@ function assertSafeDirectory(directory: string, expectedBase: 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}`);
+  }
+  let current = worktreeRoot;
+  for (const segment of ['', ...relative.split(path.sep).filter(Boolean)]) {
+    current = segment ? path.join(current, segment) : current;
+    try {
+      if (fs.lstatSync(current).isSymbolicLink()) {
+        throw new Error(`Sandbox workspace mount target must not contain a symbolic link: ${current}`);
+      }
+      const canonicalRelative = path.relative(canonicalWorktreeRoot, fs.realpathSync.native(current));
+      if (canonicalRelative.startsWith('..') || path.isAbsolute(canonicalRelative)) {
+        throw new Error(`Sandbox workspace mount target escapes its real worktree: ${current}`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+    }
+  }
+}
+
 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'));
@@ -100,41 +128,22 @@ export function assertSandboxTaskSource(repoRoot: string, taskId: string): strin
   return canonical;
 }
 
-export function prepareSandboxWorkspaceMountTarget(worktreeRoot: string): string {
-  const worktree = path.resolve(worktreeRoot);
-  const canonicalWorktree = fs.realpathSync.native(worktree);
-  const agentsRoot = path.join(worktree, '.agents');
-  if (fs.existsSync(agentsRoot)) {
-    const agentsStat = fs.lstatSync(agentsRoot);
-    if (!agentsStat.isDirectory() || agentsStat.isSymbolicLink()) {
-      throw new Error(`Sandbox workspace mount ancestor must be a real directory: ${agentsRoot}`);
-    }
-  } else {
-    fs.mkdirSync(agentsRoot, { mode: 0o700 });
-  }
-  const canonicalAgents = fs.realpathSync.native(agentsRoot);
-  if (path.dirname(canonicalAgents) !== canonicalWorktree) {
-    throw new Error(`Sandbox workspace mount ancestor escapes the worktree: ${agentsRoot}`);
+export function prepareSandboxWorkspaceMountTargets(worktreeRoot: string): void {
+  const resolvedWorktreeRoot = path.resolve(worktreeRoot);
+  const canonicalWorktreeRoot = fs.realpathSync.native(resolvedWorktreeRoot);
+  const workspaceRoot = path.resolve(resolvedWorktreeRoot, '.agents', 'workspace');
+  const statePaths = sandboxWorkspaceViewStatePaths(workspaceRoot);
+  const registryTarget = path.join(workspaceRoot, 'active', '.short-ids.json');
+  for (const target of [workspaceRoot, ...statePaths.map(({ hostPath }) => hostPath), registryTarget]) {
+    assertSafeMountTargetPath(target, resolvedWorktreeRoot, canonicalWorktreeRoot);
   }
-
-  const target = path.join(agentsRoot, 'workspace');
-  if (fs.existsSync(target)) {
-    const stat = fs.lstatSync(target);
-    if (stat.isSymbolicLink()) {
-      throw new Error(`Sandbox workspace mount target must not be a symbolic link: ${target}`);
-    }
-    if (!stat.isDirectory()) {
-      throw new Error(`Sandbox workspace mount target must be a directory: ${target}`);
-    }
-    if (path.dirname(fs.realpathSync.native(target)) !== canonicalAgents) {
-      throw new Error(`Sandbox workspace mount target escapes the worktree: ${target}`);
-    }
-  } else {
-    fs.mkdirSync(target, { mode: 0o700 });
+  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(target, 0o700);
-  fs.accessSync(target, fs.constants.W_OK);
-  return target;
+  fs.chmodSync(workspaceRoot, 0o700);
+  fs.closeSync(fs.openSync(registryTarget, 'a', 0o600));
 }
 
 export function materializeSandboxWorkspaceView(params: Readonly<{
@@ -181,16 +190,36 @@ export function materializeSandboxControl(params: Readonly<{
   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);
@@ -202,7 +231,7 @@ export function materializeSandboxControl(params: Readonly<{
   const generation = randomBytes(16).toString('hex');
   const repoRoot = fs.realpathSync.native(params.repoRoot);
   const manifest: SandboxControlManifest = {
-    version: 4,
+    version: 5,
     engine: params.engine ?? 'docker',
     repoRoot,
     worktreeRoot: fs.realpathSync.native(params.worktreeRoot),
@@ -216,10 +245,11 @@ export function materializeSandboxControl(params: Readonly<{
     generation,
     channelDir,
     publicStatusDir: statusDir,
-    processingDir
+    processingDir,
+    runtimeDir
   };
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest)}\n`, { mode: 0o600 });
-  return { root, channelDir, statusDir, manifestPath, token, generation };
+  return { root, channelDir, statusDir, runtimeDir, manifestPath, token, generation };
 }
 
 export function finalizeSandboxControlManifest(
@@ -228,7 +258,7 @@ export function finalizeSandboxControlManifest(
 ): 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 = 4;
+  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`;