@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/sandbox/commands/create.ts

@@ -69,13 +69,26 @@ import {
   prepareTmpfsMounts,
   startSandboxControlBroker
 } from '../recovery.ts';
+import {
+  acquireSandboxControlReplacement,
+  assertSandboxControlCutoverSnapshot,
+  beginSandboxControlReplacement,
+  captureSandboxControlCutoverSnapshot,
+  commitSandboxControlReplacement,
+  quiesceSandboxControlRoot,
+  recoverSandboxControlReplacement,
+  readSandboxControlManifestForTransition
+} from '../control/lifecycle.ts';
+import { inspectSandboxControlContainer } from '../control/container-identity.ts';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.ts';
 import { sandboxCoreBindMounts } from '../mounts.ts';
 import {
   assertSandboxTaskSource,
+  finalizeSandboxControlManifest,
   materializeSandboxControl,
   materializeSandboxWorkspaceView,
-  prepareSandboxWorkspaceMountTargets
+  prepareSandboxWorkspaceMountTargets,
+  sandboxControlPaths,
 } from '../workspace-view.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
 import { validateSelinuxDisableEnv } from '../engines/selinux.ts';
@@ -1035,6 +1048,12 @@ export async function create(args: string[]): Promise<void> {
   }
   const effectiveResolvedTools = resolvedTools;
   const container = containerName(effectiveConfig, branch);
+  const controlPaths = sandboxControlPaths({
+    base: effectiveConfig.controlBase,
+    project: effectiveConfig.project,
+    container,
+    identity: target.workspace
+  });
   const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
   const shareCommon = shareCommonDir(effectiveConfig);
   const shareBranch = shareBranchDir(effectiveConfig, branch);
@@ -1223,6 +1242,22 @@ export async function create(args: string[]): Promise<void> {
       {
         title: `Starting container '${container}'`,
         task: async (message: (text: string) => void) => {
+          const hadControlRootBeforeAcquire = fs.existsSync(controlPaths.root);
+          const replacementLease = acquireSandboxControlReplacement(controlPaths.root);
+          let replacementLeaseHeld = true;
+          let replacementCutover: ReturnType<typeof beginSandboxControlReplacement> | null = null;
+          try {
+            const recoveryResult = await recoverSandboxControlReplacement(controlPaths.root, replacementLease);
+            const hadExistingControlRoot = hadControlRootBeforeAcquire || recoveryResult === 'restored';
+            const previousManifest = fs.existsSync(controlPaths.manifestPath)
+              ? readSandboxControlManifestForTransition(controlPaths.manifestPath)
+              : null;
+            if (hadExistingControlRoot) {
+              await quiesceSandboxControlRoot(controlPaths.root);
+            }
+            const previousCutoverSnapshot = hadExistingControlRoot
+              ? captureSandboxControlCutoverSnapshot(controlPaths.root)
+              : null;
           const existing = runSafeEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
           const matchedContainers = containerNameCandidates(effectiveConfig, branch)
             .filter((name) => existing.includes(name));
@@ -1265,6 +1300,14 @@ export async function create(args: string[]): Promise<void> {
               runSafeEngine(engine, 'docker', ['rm', name]);
             }
           }
+          if (previousManifest) {
+            const oldContainer = await inspectSandboxControlContainer(previousManifest);
+            if (oldContainer.state !== 'absent') {
+              throw new Error(oldContainer.state === 'unknown'
+                ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${oldContainer.reason}`
+                : 'SANDBOX_CONTROL_CONTAINER_STILL_EXISTS');
+            }
+          }
 
           const aliasesFile = ensureSandboxAliasesFile(
             effectiveConfig.home,
@@ -1342,6 +1385,18 @@ export async function create(args: string[]): Promise<void> {
               identity: target.workspace
             });
             prepareSandboxWorkspaceMountTargets(worktree);
+            if (previousCutoverSnapshot) {
+              assertSandboxControlCutoverSnapshot(previousCutoverSnapshot);
+              if (previousManifest) {
+                const finalOldContainer = await inspectSandboxControlContainer(previousManifest);
+                if (finalOldContainer.state !== 'absent') {
+                  throw new Error(finalOldContainer.state === 'unknown'
+                    ? `SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${finalOldContainer.reason}`
+                    : 'SANDBOX_CONTROL_CONTAINER_REAPPEARED');
+                }
+              }
+              replacementCutover = beginSandboxControlReplacement(controlPaths.root, replacementLease);
+            }
             const control = materializeSandboxControl({
               base: effectiveConfig.controlBase,
               repoRoot: effectiveConfig.repoRoot,
@@ -1349,7 +1404,9 @@ export async function create(args: string[]): Promise<void> {
               project: effectiveConfig.project,
               container,
               branch,
-              identity: target.workspace
+              identity: target.workspace,
+              engine,
+              replacementLease
             });
             hostShellConfig = prepareHostShellConfig({
               home: effectiveConfig.home,
@@ -1363,6 +1420,7 @@ export async function create(args: string[]): Promise<void> {
               workspaceViewRoot: workspaceView.root,
               controlDir: control.channelDir,
               controlStatusDir: control.statusDir,
+              ...(target.workspace.mode === 'task-bound' ? { runtimeDir: control.runtimeDir } : {}),
               ...(target.workspace.mode === 'task-bound'
                 ? {
                   taskSource: assertSandboxTaskSource(
@@ -1422,9 +1480,12 @@ export async function create(args: string[]): Promise<void> {
             const hostTz = detectHostTimezone();
             const tzFlags = hostTz ? ['-e', `TZ=${hostTz}`] : [];
 
-            runEngineTaskCommand(engine, 'docker', [
+            let createdContainerRef: string | null = null;
+            try {
+              const dockerRunId = runEngineTaskCommand(engine, 'docker', [
               'run',
               '-d',
+              '--init',
               '--name',
               container,
               '--hostname',
@@ -1451,6 +1512,9 @@ export async function create(args: string[]): Promise<void> {
               'AGENT_INFRA_CONTROL_DIR=/run/agent-infra/control',
               '-e',
               'AGENT_INFRA_CONTROL_STATUS_DIR=/run/agent-infra/control-status',
+              ...(target.workspace.mode === 'task-bound'
+                ? ['-e', 'AGENT_INFRA_RUNTIME_DIR=/run/agent-infra/runtime']
+                : []),
               '--label',
               `${sandboxRuntimeCapabilityLabel(effectiveConfig)}=${capabilityPlan.runtimeSignature}`,
               ...coreVolumes,
@@ -1471,9 +1535,66 @@ export async function create(args: string[]): Promise<void> {
               '-w',
               '/workspace',
               effectiveConfig.imageName
-            ]);
-            await startSandboxControlBroker(effectiveConfig.repoRoot, control.manifestPath);
-            createdTmpfsSeedPlan = tmpfsSeedPlan;
+              ]);
+              createdContainerRef = dockerRunId.trim();
+              const containerId = runEngineTaskCommand(engine, 'docker', [
+                'inspect', '--format', '{{.Id}}', dockerRunId.trim()
+              ]).trim();
+              if (!containerId) throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
+              const rawContainerLabels = runEngineTaskCommand(engine, 'docker', [
+                'inspect', '--format', '{{json .Config.Labels}}', containerId
+              ]).trim();
+              let inspectedLabels: unknown;
+              try {
+                inspectedLabels = JSON.parse(rawContainerLabels);
+              } catch {
+                throw new Error('SANDBOX_CONTROL_CONTAINER_LABELS_INVALID');
+              }
+              if (!inspectedLabels || typeof inspectedLabels !== 'object' || Array.isArray(inspectedLabels)) {
+                throw new Error('SANDBOX_CONTROL_CONTAINER_LABELS_INVALID');
+              }
+              const expectedLabels: Record<string, string> = {
+                [sandboxLabel(effectiveConfig)]: '',
+                [sandboxBranchLabel(effectiveConfig)]: branch,
+                [sandboxWorkspaceModeLabel(effectiveConfig)]: target.workspace.mode,
+                [sandboxRuntimeCapabilityLabel(effectiveConfig)]: capabilityPlan.runtimeSignature,
+                ...(target.workspace.mode === 'task-bound'
+                  ? { [sandboxTaskIdLabel(effectiveConfig)]: target.workspace.taskId }
+                  : {})
+              };
+              const labels = inspectedLabels as Record<string, unknown>;
+              for (const [key, expected] of Object.entries(expectedLabels)) {
+                if (labels[key] !== expected) throw new Error('SANDBOX_CONTROL_CONTAINER_IDENTITY_MISMATCH');
+              }
+              finalizeSandboxControlManifest(control, {
+                engine,
+                id: containerId,
+                labels: expectedLabels
+              });
+              replacementLease.clearQuiescing();
+              await startSandboxControlBroker(effectiveConfig.repoRoot, control.manifestPath);
+              if (replacementCutover) {
+                commitSandboxControlReplacement(control.root, replacementLease);
+                replacementCutover = null;
+              }
+              createdTmpfsSeedPlan = tmpfsSeedPlan;
+            } catch (error) {
+              if (createdContainerRef) {
+                runSafeEngine(engine, 'docker', ['stop', createdContainerRef]);
+                runSafeEngine(engine, 'docker', ['rm', createdContainerRef]);
+              }
+              if (!hadExistingControlRoot) removeDirRecursive(control.root);
+              if (replacementCutover) {
+                try {
+                  await recoverSandboxControlReplacement(control.root, replacementLease);
+                  replacementCutover = null;
+                } catch {
+                  // Preserve the cutover state for the next explicit recreate to recover.
+                }
+              }
+              removeDirRecursive(workspaceView.root);
+              throw error;
+            }
           } finally {
             envFile.cleanup();
           }
@@ -1566,7 +1687,19 @@ export async function create(args: string[]): Promise<void> {
             );
           }
 
+          replacementLease.release();
+          replacementLeaseHeld = false;
           return 'Container started';
+          } catch (error) {
+            if (replacementLeaseHeld) {
+              try {
+                replacementLease.release();
+              } catch {
+                // Preserve the original cutover failure and its evidence.
+              }
+            }
+            throw error;
+          }
         }
       }
     ]);

package/lib/sandbox/commands/rm.ts

@@ -20,7 +20,8 @@ import { assertManagedPath, removeManagedDir, removeWorktreeDir } from '../manag
 import { runEngine, runOk, runOkEngine, runSafe, runSafeEngine } from '../shell.ts';
 import { resolveSandboxTarget, type SandboxWorkspaceIdentity } from '../workspace-identity.ts';
 import { sandboxControlPaths, sandboxWorkspaceViewPaths } from '../workspace-view.ts';
-import { quiesceSandboxControlRoot, readSandboxControlManifest } from '../control/lifecycle.ts';
+import { removeSandboxControlRoot, readSandboxControlManifest } from '../control/lifecycle.ts';
+import { inspectSandboxControlContainer } from '../control/container-identity.ts';
 import { toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
 import { createSandboxCapabilityPlan } from '../agent-client-reconciler.ts';
 import type { SandboxTool } from '../tools.ts';
@@ -172,9 +173,40 @@ function removeEmptyManagedParent(base: string, directory: string): void {
   assertRemoved(parent, 'Empty sandbox container directory');
 }
 
-async function quiesceProjectControlRoots(config: SandboxConfig): Promise<void> {
+async function removeExactSandboxContainer(
+  engine: string,
+  manifest: ReturnType<typeof readSandboxControlManifest>,
+  timeoutMs: number
+): Promise<void> {
+  const deadlineAt = Date.now() + timeoutMs;
+  const remaining = (): number => Math.max(1, deadlineAt - Date.now());
+  const inspect = () => inspectSandboxControlContainer(manifest, { timeoutMs: remaining() });
+  const before = await inspect();
+  if (before.state === 'unknown') throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${before.reason}`);
+  if (before.state === 'absent') return;
+  if (before.running && !runOkEngine(engine, 'docker', ['stop', manifest.containerIdentity.id], { timeout: remaining() })) {
+    const afterStop = await inspect();
+    if (afterStop.state !== 'absent' && afterStop.state !== 'found') {
+      throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterStop.reason}`);
+    }
+    if (afterStop.state === 'found' && afterStop.running) {
+      throw new Error(`Failed to stop sandbox container: ${manifest.containerIdentity.id}`);
+    }
+  }
+  const afterStop = await inspect();
+  if (afterStop.state === 'unknown') throw new Error(`SANDBOX_CONTROL_CONTAINER_UNKNOWN: ${afterStop.reason}`);
+  if (afterStop.state === 'found' && !runOkEngine(engine, 'docker', ['rm', manifest.containerIdentity.id], { timeout: remaining() })) {
+    const afterRemove = await inspect();
+    if (afterRemove.state !== 'absent') {
+      throw new Error(`Failed to remove sandbox container: ${manifest.containerIdentity.id}`);
+    }
+  }
+}
+
+async function removeProjectControlRoots(config: SandboxConfig, engine: string): Promise<Set<string>> {
+  const containers = new Set<string>();
   const projectRoot = path.join(config.controlBase, config.project);
-  if (!fs.existsSync(projectRoot)) return;
+  if (!fs.existsSync(projectRoot)) return containers;
   assertManagedPath(config.controlBase, projectRoot);
   const projectStat = fs.lstatSync(projectRoot);
   if (!projectStat.isDirectory() || projectStat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
@@ -183,9 +215,18 @@ async function quiesceProjectControlRoots(config: SandboxConfig): Promise<void>
     const containerRoot = path.join(projectRoot, container.name);
     for (const identity of fs.readdirSync(containerRoot, { withFileTypes: true })) {
       if (!identity.isDirectory() || identity.isSymbolicLink()) continue;
-      await quiesceSandboxControlRoot(path.join(containerRoot, identity.name));
+      const root = path.join(containerRoot, identity.name);
+      const manifestPath = path.join(root, 'manifest.json');
+      if (!fs.existsSync(manifestPath)) throw new Error(`SANDBOX_CONTROL_TARGET_EVIDENCE_MISSING: ${root}`);
+      const manifest = readSandboxControlManifest(manifestPath);
+      containers.add(manifest.container);
+      await removeSandboxControlRoot(root, {
+        inspectContainer: (timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }),
+        removeContainer: (timeoutMs) => removeExactSandboxContainer(engine, manifest, timeoutMs)
+      });
     }
   }
+  return containers;
 }
 
 function inspectionBlockers(inspections: readonly WorktreeInspection[]): WorktreeInspection[] {
@@ -277,23 +318,30 @@ async function rmOne(
     return;
   }
 
+  const coordinatedContainers = new Set<string>();
   for (const root of controlRoots.filter((candidate) => fs.existsSync(candidate))) {
     assertLegacyCandidateEvidence(root, config.controlBase, config, effectiveBranch, matchedContainers);
     assertControlRootMatchesTarget(root, effectiveBranch, workspace);
-    await quiesceSandboxControlRoot(root);
+    const manifest = readSandboxControlManifest(path.join(root, 'manifest.json'));
+    coordinatedContainers.add(manifest.container);
+    await removeSandboxControlRoot(root, {
+      inspectContainer: (timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }),
+      removeContainer: (timeoutMs) => removeExactSandboxContainer(engine, manifest, timeoutMs)
+    });
   }
 
-  if (matchedContainers.length > 0) {
+  const uncoordinatedContainers = matchedContainers.filter((name) => !coordinatedContainers.has(name));
+  if (uncoordinatedContainers.length > 0) {
     const spinner = p.spinner();
-    spinner.start(`Stopping container(s): ${matchedContainers.join(', ')}`);
-    for (const name of matchedContainers) {
+    spinner.start(`Stopping container(s): ${uncoordinatedContainers.join(', ')}`);
+    for (const name of uncoordinatedContainers) {
       if (!runOkEngine(engine, 'docker', ['stop', name])) throw new Error(`Failed to stop sandbox container: ${name}`);
       if (!runOkEngine(engine, 'docker', ['rm', name])) throw new Error(`Failed to remove sandbox container: ${name}`);
     }
     const remaining = runEngine(engine, 'docker', ['ps', '-a', '--format', '{{.Names}}']).split('\n').filter(Boolean);
-    const leftovers = matchedContainers.filter((name) => remaining.includes(name));
+    const leftovers = uncoordinatedContainers.filter((name) => remaining.includes(name));
     if (leftovers.length > 0) throw new Error(`Sandbox container(s) still exist after removal: ${leftovers.join(', ')}`);
-    spinner.stop(pc.green(`Removed container(s): ${matchedContainers.join(', ')}`));
+    spinner.stop(pc.green(`Removed container(s): ${uncoordinatedContainers.join(', ')}`));
   } else {
     p.log.warn(`No sandbox container found for '${branch}'`);
   }
@@ -400,7 +448,7 @@ async function rmPurge(
   }
   const permits = cleanPermits(inspections);
 
-  await quiesceProjectControlRoots(config);
+  const coordinatedContainers = await removeProjectControlRoots(config, engine);
 
   const containers = runEngine(engine, 'docker', [
     'ps',
@@ -410,17 +458,19 @@ async function rmPurge(
     '--format',
     '{{.Names}}'
   ]);
-  if (containers) {
+  const uncoordinatedContainers = containers.split('\n').filter((name) => name && !coordinatedContainers.has(name));
+  if (uncoordinatedContainers.length > 0) {
     const spinner = p.spinner();
     spinner.start('Stopping project sandbox containers...');
-    for (const name of containers.split('\n').filter(Boolean)) {
+    for (const name of uncoordinatedContainers) {
       if (!runOkEngine(engine, 'docker', ['stop', name])) throw new Error(`Failed to stop sandbox container: ${name}`);
       if (!runOkEngine(engine, 'docker', ['rm', name])) throw new Error(`Failed to remove sandbox container: ${name}`);
     }
     const remaining = runEngine(engine, 'docker', [
       'ps', '-a', '--filter', `label=${sandboxLabel(config)}`, '--format', '{{.Names}}'
     ]);
-    if (remaining) throw new Error(`Project sandbox container(s) still exist after removal: ${remaining.replaceAll('\n', ', ')}`);
+    const leftovers = remaining.split('\n').filter((name) => name && !coordinatedContainers.has(name));
+    if (leftovers.length > 0) throw new Error(`Project sandbox container(s) still exist after removal: ${leftovers.join(', ')}`);
     spinner.stop(pc.green('Project sandbox containers removed'));
   } else {
     p.log.warn('No project sandbox containers found');

package/lib/sandbox/commands/start.ts

@@ -17,9 +17,9 @@ const USAGE = `Usage: ai sandbox start [--recreate] <branch | TASK-id | N>
 
 Start an existing sandbox container that has stopped (for example after the
 Docker daemon was restarted or replaced). The container must already exist:
-if none is found, run 'ai sandbox create <branch>' first. A container that is
-already running is checked without modifying healthy runtime state. --recreate
-allows container-only replacement after in-place recovery fails.`;
+if none is found, run 'ai sandbox create <branch>' first. Without --recreate, a
+container that is already running is checked without modifying healthy runtime
+state. --recreate replaces the existing container even when it is healthy.`;
 
 export function parseStartArgs(args: string[]): { target: string; recreate: boolean; help: boolean } {
   let recreate = false;
@@ -83,6 +83,7 @@ export async function start(args: string[]): Promise<void> {
     workspace: target.workspace,
     row: found,
     allowRecreate: parsed.recreate,
+    forceRecreate: parsed.recreate,
     recreate: async () => {
       const { create } = await import('./create.ts');
       await create([target.requestedRef, '--no-refresh']);

package/lib/sandbox/config.ts

@@ -7,6 +7,7 @@ import { normalizeAgentClients } from '../agent-clients/config.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientState } from '../agent-clients/types.ts';
 import { validateSandboxEngine } from './engine.ts';
+import type { SandboxEngineInput } from './engine.ts';
 import { hostJoin } from './engines/wsl2-paths.ts';
 import { findRuntimeEngineMismatches } from './runtime-engines.ts';
 import { parseCustomTools } from './tools.ts';
@@ -29,7 +30,7 @@ type PlatformFn = typeof platform;
 type WriteStderr = (chunk: string) => unknown;
 
 type SandboxConfigInput = {
-  engine?: string | null;
+  engine?: SandboxEngineInput;
   runtimes?: string[];
   tools?: string[];
   customTools?: unknown;

package/lib/sandbox/control/container-identity.ts

@@ -0,0 +1,93 @@
+import type { SandboxControlManifest, SandboxControlManifestLike } from './protocol.ts';
+import { commandForEngine, runEngine, runProbe } from '../shell.ts';
+
+export type ContainerObservation =
+  | Readonly<{ state: 'found'; id: string; running: boolean; labels: Readonly<Record<string, string>> }>
+  | Readonly<{ state: 'absent'; id: string }>
+  | Readonly<{ state: 'unknown'; reason: string }>;
+
+export type ContainerInspection = Readonly<{
+  id?: unknown;
+  running?: unknown;
+  labels?: unknown;
+}>;
+
+function isAuthoritativeNotFound(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return /(?:no such (?:container|object)|container .* not found|cannot find container)/i.test(message);
+}
+
+export function classifySandboxContainerInspection(
+  expected: SandboxControlManifest['containerIdentity'],
+  inspection: ContainerInspection | { notFound: true } | { error: unknown }
+): ContainerObservation {
+  if ('notFound' in inspection) return { state: 'absent', id: expected.id };
+  if ('error' in inspection) {
+    return isAuthoritativeNotFound(inspection.error)
+      ? { state: 'absent', id: expected.id }
+      : { state: 'unknown', reason: `container inspection failed: ${inspection.error instanceof Error ? inspection.error.message : String(inspection.error)}` };
+  }
+  const response = inspection as ContainerInspection;
+  if (typeof response.id !== 'string' || response.id !== expected.id
+    || typeof response.running !== 'boolean' || !response.labels
+    || typeof response.labels !== 'object' || Array.isArray(response.labels)) {
+    return { state: 'unknown', reason: 'container inspection response is incomplete' };
+  }
+  const labels = response.labels as Record<string, unknown>;
+  for (const [key, value] of Object.entries(expected.labels)) {
+    if (labels[key] !== value) return { state: 'unknown', reason: 'container labels do not match the manifest' };
+  }
+  return {
+    state: 'found',
+    id: response.id,
+    running: response.running,
+    labels: Object.fromEntries(
+      Object.entries(labels).flatMap(([key, value]) => typeof value === 'string' ? [[key, value]] : [])
+    )
+  };
+}
+
+export async function inspectSandboxControlContainer(
+  manifest: SandboxControlManifestLike,
+  options: { run?: typeof runEngine; probe?: typeof runProbe; timeoutMs?: number } = {}
+): Promise<ContainerObservation> {
+  try {
+    const args = ['inspect', '--format', '{{json .}}', manifest.containerIdentity.id];
+    let raw: string;
+    if (options.run) {
+      raw = options.run(manifest.engine, 'docker', args, options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs });
+    } else {
+      const command = commandForEngine(manifest.engine, 'docker', args);
+      const result = (options.probe ?? runProbe)(
+        command.cmd,
+        command.args,
+        options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs }
+      );
+      if (result.status !== 0) {
+        const stderr = typeof result.stderr === 'string' ? result.stderr : result.stderr?.toString('utf8') ?? '';
+        return classifySandboxContainerInspection(manifest.containerIdentity, {
+          error: new Error(stderr || `container inspection exited with ${result.status ?? 'unknown'}`)
+        });
+      }
+      raw = typeof result.stdout === 'string' ? result.stdout : result.stdout?.toString('utf8') ?? '';
+    }
+    const parsed = JSON.parse(raw) as {
+      Id?: unknown;
+      State?: { Running?: unknown };
+      Config?: { Labels?: unknown };
+    } | Array<{
+      Id?: unknown;
+      State?: { Running?: unknown };
+      Config?: { Labels?: unknown };
+    }>;
+    const value = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : parsed;
+    if (!value || Array.isArray(value)) return { state: 'unknown', reason: 'container inspection response is incomplete' };
+    return classifySandboxContainerInspection(manifest.containerIdentity, {
+      id: value.Id,
+      running: value.State?.Running,
+      labels: value.Config?.Labels
+    });
+  } catch (error) {
+    return classifySandboxContainerInspection(manifest.containerIdentity, { error });
+  }
+}

package/lib/sandbox/control/executor.ts

@@ -15,9 +15,9 @@ export type SandboxControlExecutionResult = {
 
 export type PreparedSandboxControlExecution = {
   execution: SandboxControlExecution;
-  start(): void;
+  start(canWrite?: () => boolean): void;
   completion: Promise<SandboxControlExecutionResult>;
-  terminate(): boolean;
+  terminate(updateState?: boolean): boolean;
 };
 
 function safeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
@@ -30,11 +30,11 @@ export function nodeEntryArgs(entry: string, args: string[]): string[] {
     : [entry, ...args];
 }
 
-async function waitForStartTime(pid: number, timeoutMs = 2_000): Promise<string> {
+async function waitForStartTime(pid: number, timeoutMs = 2_000): Promise<number> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     const startTime = getProcessStartTime(pid);
-    if (startTime) return startTime;
+    if (startTime !== null) return startTime;
     await new Promise<void>((resolve) => setTimeout(resolve, 10));
   }
   throw new Error('SANDBOX_CONTROL_EXECUTOR_IDENTITY_UNAVAILABLE');
@@ -57,7 +57,11 @@ export async function prepareSandboxControlExecution(params: {
       cwd: params.manifest.repoRoot,
       detached: process.platform !== 'win32',
       stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
-      env: { ...safeEnv(process.env), AGENT_INFRA_EXECUTOR_MANIFEST: params.manifestPath }
+      env: {
+        ...safeEnv(process.env),
+        AGENT_INFRA_EXECUTOR_MANIFEST: params.manifestPath,
+        AGENT_INFRA_RUNTIME_DIR: params.manifest.runtimeDir
+      }
     }
   );
   if (typeof child.pid !== 'number') throw new Error('SANDBOX_CONTROL_EXECUTOR_SPAWN_FAILED');
@@ -73,7 +77,7 @@ export async function prepareSandboxControlExecution(params: {
   });
   const startTime = await waitForStartTime(child.pid);
   const execution: SandboxControlExecution = {
-    version: 1,
+    version: 2,
     generation: params.manifest.generation,
     requestId: params.request.id,
     nonce,
@@ -88,16 +92,20 @@ export async function prepareSandboxControlExecution(params: {
   atomicWriteJson(executionPath(params.manifest, params.request.id), execution);
   return {
     execution,
-    start() {
+    start(canWrite = () => true) {
       if (!child.connected) throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED');
+      if (!canWrite()) throw new Error('SANDBOX_CONTROL_OWNER_LOST');
       atomicWriteJson(executionPath(params.manifest, params.request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
+      if (!canWrite()) throw new Error('SANDBOX_CONTROL_OWNER_LOST');
       child.send({ version: 1, nonce });
     },
     completion,
-    terminate() {
-      atomicWriteJson(executionPath(params.manifest, params.request.id), {
-        ...execution, phase: 'terminating', updatedAt: Date.now()
-      });
+    terminate(updateState = true) {
+      if (updateState) {
+        atomicWriteJson(executionPath(params.manifest, params.request.id), {
+          ...execution, phase: 'terminating', updatedAt: Date.now()
+        });
+      }
       return terminateSandboxControlExecution(execution);
     }
   };
@@ -138,7 +146,11 @@ function executeRequest(manifest: SandboxControlManifest, request: SandboxContro
   const result = spawnSync(
     process.execPath,
     nodeEntryArgs(process.argv[1]!, [request.family, ...boundArgs]),
-    { cwd: manifest.repoRoot, encoding: 'utf8', env: safeEnv(process.env) }
+    {
+      cwd: manifest.repoRoot,
+      encoding: 'utf8',
+      env: { ...safeEnv(process.env), AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir }
+    }
   );
   return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
 }