@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/lib/sandbox/control/protocol.ts

@@ -1,12 +1,14 @@
 import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../task/create.ts';
+import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
 import type { ProcessIdentity } from '../../server/process-state.ts';
+import type { CodexControllerLeaseProofV1 } from './controller-registration.ts';
 
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
 export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
 export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
 export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
 export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
-export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'] as const;
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-finalization', 'task-create', 'codex-controller'] as const;
 export type SandboxControlTimingPolicy = Readonly<{
   controlTickMs: number;
   parkedBindingInitialMs: number;
@@ -27,12 +29,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;
@@ -40,15 +45,25 @@ export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
   generation: string;
 }>;
 type RequestBase = Readonly<{
-  version: 2; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
+  version: 3; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
+  controllerProcess: ProcessIdentity | null;
+  controllerProof: CodexControllerLeaseProofV1 | null;
 }>;
 export type SandboxTaskCommandRequest = RequestBase & Readonly<{
   family: 'task-lifecycle' | 'task-orchestration'; args: string[];
 }>;
+export type SandboxTaskFinalizationRequest = RequestBase & Readonly<{
+  family: 'task-finalization'; operation: 'complete'; agent: string; args: [];
+}>;
 export type SandboxTaskCreateRequest = RequestBase & Readonly<{
   family: 'task-create'; candidate: TaskCreateCandidateV1;
 }>;
-export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskCreateRequest;
+export type SandboxCodexControllerRequest = RequestBase & Readonly<{
+  family: 'codex-controller';
+  command: 'open' | 'close' | 'verify';
+  args: [];
+}>;
+export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest;
 export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
 export type SandboxControlResponse = Readonly<{
   version: 2; id: string; phase: 'accepted' | 'completed' | 'rejected'; exitCode: number | null;
@@ -98,7 +113,7 @@ export function validateSandboxControlRequest(
   }
   const request = value as Record<string, unknown>;
   if (
-    request.version !== 2 || typeof request.id !== 'string'
+    request.version !== 3 || typeof request.id !== 'string'
     || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
     || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
     || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt)
@@ -117,13 +132,47 @@ export function validateSandboxControlRequest(
     fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
   }
   if (request.family === 'task-create') {
-    const expected = ['candidate', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    const expected = ['candidate', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
     if (Object.keys(request).sort().join(',') !== expected.sort().join(',')) {
       fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
     }
+    if (request.controllerProcess !== null || request.controllerProof !== null) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create cannot carry controller authority');
+    }
     return { ...request, candidate: validateTaskCreateCandidate(request.candidate) } as SandboxTaskCreateRequest;
   }
-  const expected = ['args', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+  if (request.family === 'codex-controller') {
+    const expected = ['args', 'command', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+      || !Array.isArray(request.args) || request.args.length !== 0
+      || !['open', 'close', 'verify'].includes(request.command as string)
+      || !validControllerProcess(request.controllerProcess)
+      || (request.command === 'open' && request.controllerProof !== null)
+      || (request.command !== 'open' && !validControllerProof(request.controllerProof))
+      || (request.command === 'verify'
+        && JSON.stringify(request.controllerProcess) !== JSON.stringify((request.controllerProof as CodexControllerLeaseProofV1).controllerProcess))) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller request schema is invalid');
+    }
+    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot register a Codex controller');
+    }
+    return request as SandboxCodexControllerRequest;
+  }
+  if (request.family === 'task-finalization') {
+    const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'token', 'version'];
+    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+      || request.operation !== 'complete'
+      || !Array.isArray(request.args) || request.args.length !== 0
+      || typeof request.agent !== 'string' || normalizeAgentToken(request.agent) !== request.agent
+      || request.controllerProcess !== null || request.controllerProof !== null) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization request schema or authorization is invalid');
+    }
+    if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+      fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks');
+    }
+    return request as SandboxTaskFinalizationRequest;
+  }
+  const expected = ['args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
   if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
     || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
@@ -138,15 +187,42 @@ export function validateSandboxControlRequest(
     && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))) {
     fail('SANDBOX_CONTROL_REQUEST_INVALID', 'worktree binding is reserved for the control broker');
   }
+  if (request.controllerProcess !== null
+    || (request.controllerProof !== null && !validControllerProof(request.controllerProof))) {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller authority is invalid');
+  }
+  if (request.family !== 'task-orchestration' && request.controllerProof !== null) {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'controller proof is not allowed for this family');
+  }
   return request as SandboxTaskCommandRequest;
 }
 
 export function bindSandboxControlTask(request: SandboxControlRequest, taskId: string): string[] {
-  if (request.family === 'task-create') fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create requests do not bind a current task');
+  if (request.family === 'task-create' || request.family === 'codex-controller' || request.family === 'task-finalization') {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', `${request.family} requests do not bind a current task`);
+  }
   if (request.args.length === 0) fail('SANDBOX_CONTROL_REQUEST_INVALID', 'command arguments are required');
   return [taskId, ...request.args.slice(1)];
 }
 
+function validControllerProcess(value: unknown): value is ProcessIdentity {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const processValue = value as Record<string, unknown>;
+  return Object.keys(processValue).sort().join(',') === 'pid,startTime'
+    && Number.isSafeInteger(processValue.pid) && (processValue.pid as number) > 0
+    && Number.isSafeInteger(processValue.startTime) && (processValue.startTime as number) >= 0;
+}
+
+function validControllerProof(value: unknown): value is CodexControllerLeaseProofV1 {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const proof = value as Record<string, unknown>;
+  return Object.keys(proof).sort().join(',') === 'controllerProcess,leaseId,leaseSecret,version'
+    && proof.version === 1
+    && typeof proof.leaseId === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseId)
+    && typeof proof.leaseSecret === 'string' && /^[a-f0-9]{64}$/u.test(proof.leaseSecret)
+    && validControllerProcess(proof.controllerProcess);
+}
+
 export function controlError(error: unknown): SandboxControlError {
   if (error instanceof SandboxControlProtocolError) {
     return { code: error.code, message: error.message, retryable: error.retryable };

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/index.ts

@@ -15,9 +15,11 @@ Commands:
   rebuild [--quiet] [--refresh]
                                Rebuild the sandbox image (--refresh pulls base + tools)
   refresh                      Sync host Claude Code credentials to all sandbox copies
-  rm <branch> | --unbound | --purge
-                               Remove one sandbox, all sandboxes not bound to an
-                               active task (--unbound), or tear down everything (--purge)
+  rm <branch | TASK-id> | --unbound | --purge
+                               Remove one sandbox; use a full TASK-id for task-bound
+                               cleanup and a branch for branch-only cleanup. --unbound
+                               removes completed task-bound and branch-only sandboxes;
+                               active, blocked, and archive tasks are protected.
   start [--recreate] <branch | TASK-id | N>
                                Verify or recover an existing sandbox container;
                                optionally replace only the container on failure

package/lib/sandbox/managed-fs.ts

@@ -36,6 +36,11 @@ export function removeWorktreeDir(
     throw new Error(`Worktree permit target mismatch: ${dir}`);
   }
   verifyWorktreePermit(permit);
+  if (permit.snapshot.source === 'recovered') {
+    removeManagedDir(worktreeBase, dir);
+    runSafeFn('git', ['-C', repoRoot, 'worktree', 'prune']);
+    return;
+  }
   try {
     runFn('git', ['-C', repoRoot, 'worktree', 'remove', dir, '--force']);
   } catch (error) {

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)(