@fitlab-ai/agent-infra 0.9.9 → 0.9.11

package/lib/sandbox/commands/enter.ts

@@ -3,7 +3,9 @@ import {
   assertValidBranchName,
   containerNameCandidates,
   sandboxBranchLabel,
-  sandboxLabel
+  sandboxLabel,
+  sandboxTaskIdLabel,
+  sandboxWorkspaceModeLabel
 } from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import { ensureSandboxReady } from '../recovery.ts';
@@ -21,7 +23,10 @@ import {
   fetchSandboxRows,
   selectSandboxContainer,
 } from './list-running.ts';
-import { resolveSandboxTarget } from '../workspace-identity.ts';
+import {
+  resolveSandboxReentryContext,
+  resolveSandboxTarget
+} from '../workspace-identity.ts';
 
 const USAGE = `Usage: ai sandbox exec [--recreate] <branch | TASK-id | N> [cmd...]
 
@@ -128,7 +133,11 @@ export async function enter(args: string[]): Promise<number> {
   const { running, nonRunning } = fetchSandboxRows(
     engine,
     sandboxLabel(config),
-    sandboxBranchLabel(config)
+    sandboxBranchLabel(config),
+    {
+      mode: sandboxWorkspaceModeLabel(config),
+      taskId: sandboxTaskIdLabel(config)
+    }
   );
   const found = selectSandboxContainer(
     [...running, ...nonRunning],
@@ -140,11 +149,22 @@ export async function enter(args: string[]): Promise<number> {
       `No sandbox found for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`
     );
   }
+  const containerWorkspace = found.workspaceMode === 'task-bound' && found.taskId
+    ? { mode: 'task-bound' as const, taskId: found.taskId }
+    : found.workspaceMode === 'branch-only'
+      ? { mode: 'branch-only' as const }
+      : { mode: 'legacy-invalid' as const };
+  const reentry = resolveSandboxReentryContext({
+    target,
+    containerWorkspace,
+    repoRoot: config.repoRoot
+  });
   const ready = await ensureSandboxReady({
     config,
     engine,
     branch,
-    workspace: target.workspace,
+    workspace: reentry.workspace,
+    reentry: reentry.reentry,
     row: found,
     allowRecreate: parsed.recreate,
     recreate: async () => {

package/lib/sandbox/config.ts

@@ -4,7 +4,6 @@ import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import pc from 'picocolors';
 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';
@@ -64,7 +63,6 @@ export type SandboxConfig = {
   tools: string[];
   customTools: SandboxTool[];
   agentClientState: AgentClientState;
-  agentClientSource: 'canonical' | 'legacy';
   refreshIntervalDays: number;
   dockerfile: string | null;
   vm: SandboxVmConfig;
@@ -74,7 +72,6 @@ type AircConfig = {
   project?: unknown;
   org?: unknown;
   agentClients?: unknown;
-  tuis?: unknown;
   sandbox?: SandboxConfigInput;
 };
 
@@ -110,17 +107,10 @@ function cloneDefaults(): SandboxConfigInput & { vm: SandboxVmConfig; runtimes:
 
 function resolveSandboxToolIds(
   sandbox: SandboxConfigInput,
-  agentClients: ReturnType<typeof normalizeAgentClients>,
   defaults: readonly string[]
 ): string[] {
   if (Array.isArray(sandbox.tools)) {
-    const tools = sandbox.tools.filter((tool): tool is string => typeof tool === 'string');
-    return agentClients.source === 'canonical'
-      ? tools.filter((tool) => !isAgentClientId(tool))
-      : tools;
-  }
-  if (agentClients.remainingSandboxTools !== undefined) {
-    return [...agentClients.remainingSandboxTools];
+    return sandbox.tools.filter((tool): tool is string => typeof tool === 'string');
   }
   return [...defaults];
 }
@@ -142,7 +132,6 @@ export function loadConfig({
   }
 
   const airc = JSON.parse(fs.readFileSync(configPath, 'utf8')) as AircConfig;
-  const sandboxInput = airc.sandbox;
   const agentClients = normalizeAgentClients(airc);
   const defaults = cloneDefaults();
   const sandbox = airc.sandbox ?? {};
@@ -178,7 +167,7 @@ export function loadConfig({
   }
 
   const customTools = parseCustomTools(sandbox.customTools, { home });
-  const tools = resolveSandboxToolIds(sandbox, agentClients, defaults.tools);
+  const tools = resolveSandboxToolIds(sandbox, defaults.tools);
 
   return {
     repoRoot,
@@ -199,7 +188,6 @@ export function loadConfig({
     tools,
     customTools,
     agentClientState: agentClients.state,
-    agentClientSource: agentClients.source,
     refreshIntervalDays: asNonNegativeIntegerOrDefault(
       sandbox.refreshIntervalDays,
       defaults.refreshIntervalDays

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

@@ -1,4 +1,4 @@
-import type { SandboxControlManifest, SandboxControlManifestLike } from './protocol.ts';
+import type { SandboxControlManifest } from './protocol.ts';
 import { commandForEngine, runEngine, runProbe } from '../shell.ts';
 
 export type ContainerObservation =
@@ -48,7 +48,7 @@ export function classifySandboxContainerInspection(
 }
 
 export async function inspectSandboxControlContainer(
-  manifest: SandboxControlManifestLike,
+  manifest: SandboxControlManifest,
   options: { run?: typeof runEngine; probe?: typeof runProbe; timeoutMs?: number } = {}
 ): Promise<ContainerObservation> {
   try {

package/lib/sandbox/control/controller-registration.ts

@@ -188,10 +188,12 @@ function assertRegistrationBinding(
 ): void {
   if (registration.taskId !== manifest.taskId
     || registration.controlGeneration !== manifest.generation
-    || registration.containerId !== manifest.containerIdentity.id
-    || JSON.stringify(registration.buildIdentity) !== JSON.stringify(buildIdentity)) {
+    || registration.containerId !== manifest.containerIdentity.id) {
     fail('CODEX_SANDBOX_CONTROLLER_REGISTRATION_INVALID', 'controller registration binding is invalid');
   }
+  if (registration.buildIdentity.protocolVersion !== buildIdentity.protocolVersion) {
+    fail('CODEX_LIFECYCLE_PROTOCOL_MISMATCH', 'Codex lifecycle protocol version does not match');
+  }
 }
 
 function atomicWrite(file: string, value: CodexControllerRegistrationV1): void {
@@ -322,7 +324,10 @@ export function resolveCodexControllerBinding(params: Readonly<{
   buildIdentity: LifecycleBuildIdentity;
   now?: number;
   probeProcess?: (identity: ProcessIdentity) => ProcessIdentityState;
-}>): Readonly<{ instanceDigest: string; controlGeneration: string }> {
+}>): Readonly<{
+  instanceDigest: string;
+  controlGeneration: string;
+}> {
   if (params.manifest.mode !== 'task-bound' || !params.manifest.taskId) {
     fail('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot resolve a Codex controller registration');
   }

package/lib/sandbox/control/executor.ts

@@ -1,13 +1,19 @@
-import { spawn, spawnSync, type ChildProcess } from 'node:child_process';
+import { spawn, type ChildProcess } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.ts';
 import { createTask } from '../../task/create-service.ts';
 import { applyTaskFinalization } from '../../task/finalization.ts';
-import { verifyTaskEvent } from '../../task/verification.ts';
-import { bindSandboxControlTask, type SandboxControlExecution, type SandboxControlManifest, type SandboxControlRequest } from './protocol.ts';
-import { atomicWriteJson, executionPath, terminateSandboxControlExecution } from './state.ts';
+import { bindSandboxControlTask, validateSandboxControlRequest, type SandboxControlExecution, type SandboxControlManifest, type SandboxControlRequest } from './protocol.ts';
+import { atomicWriteJson, executionPath, readActiveLease, terminateSandboxControlExecution } from './state.ts';
+import {
+  createSandboxExecutorExecutionContext,
+  dispatchTaskControlOperation,
+  parseTaskControlOperation,
+  type TaskControlOperation
+} from '../../task/control-authority.ts';
+import { assertSandboxControlBrokerOwner, readSandboxControlManifest, type BrokerOwner } from './lifecycle.ts';
 import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.ts';
 import {
   closeCodexControllerRegistration,
@@ -29,6 +35,26 @@ export type PreparedSandboxControlExecution = {
   terminate(updateState?: boolean): boolean;
 };
 
+function sameBrokerOwner(left: BrokerOwner, right: BrokerOwner): boolean {
+  return left.version === right.version
+    && left.pid === right.pid
+    && left.startTime === right.startTime
+    && left.brokerId === right.brokerId
+    && left.token === right.token
+    && left.generation === right.generation;
+}
+
+export function assertSandboxControlExecutorAuthority(
+  manifest: SandboxControlManifest,
+  gateOwner?: BrokerOwner
+): void {
+  const owner = assertSandboxControlBrokerOwner(manifest);
+  if (gateOwner && !sameBrokerOwner(owner, gateOwner)) {
+    throw new Error('SANDBOX_CONTROL_GATE_OWNER_MISMATCH');
+  }
+  if (readActiveLease(manifest)) throw new Error('SANDBOX_CONTROL_HANDOFF_ACTIVE');
+}
+
 function safeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
   return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
 }
@@ -104,9 +130,11 @@ export async function prepareSandboxControlExecution(params: {
     start(canWrite = () => true) {
       if (!child.connected) throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED');
       if (!canWrite()) throw new Error('SANDBOX_CONTROL_OWNER_LOST');
+      const gateOwner = assertSandboxControlBrokerOwner(params.manifest);
+      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 });
+      child.send({ version: 1, nonce, owner: gateOwner });
     },
     completion,
     terminate(updateState = true) {
@@ -120,7 +148,7 @@ export async function prepareSandboxControlExecution(params: {
   };
 }
 
-function waitForGate(nonce: string, timeoutMs = 2_000): Promise<void> {
+function waitForGate(nonce: string, timeoutMs = 2_000): Promise<BrokerOwner> {
   return new Promise((resolve, reject) => {
     const timer = setTimeout(() => reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_TIMEOUT')), timeoutMs);
     const onDisconnect = () => {
@@ -131,12 +159,21 @@ function waitForGate(nonce: string, timeoutMs = 2_000): Promise<void> {
     process.once('message', (message: unknown) => {
       clearTimeout(timer);
       process.off('disconnect', onDisconnect);
-      const value = message as { version?: unknown; nonce?: unknown } | null;
-      if (!value || value.version !== 1 || value.nonce !== nonce) {
+      const value = message as {
+        version?: unknown;
+        nonce?: unknown;
+        owner?: Partial<BrokerOwner> | null;
+      } | null;
+      const owner = value?.owner;
+      if (!value || value.version !== 1 || value.nonce !== nonce
+        || !owner || owner.version !== 3 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
+        || typeof owner.startTime !== 'number' || !Number.isSafeInteger(owner.startTime)
+        || typeof owner.brokerId !== 'string' || owner.brokerId.length === 0
+        || typeof owner.token !== 'string' || typeof owner.generation !== 'string') {
         reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_INVALID'));
         return;
       }
-      resolve();
+      resolve(owner as BrokerOwner);
     });
   });
 }
@@ -146,12 +183,15 @@ function controllerFailure(error: unknown): SandboxControlExecutionResult {
     ? error.code
     : /^([A-Z][A-Z0-9_]+)/u.exec(error instanceof Error ? error.message : String(error))?.[1]
       ?? 'CODEX_SANDBOX_CONTROLLER_FAILED';
+  const message = error instanceof CodexControllerRegistrationError
+    ? error.message
+    : `${code}: controller operation failed; inspect the sandbox controller and rebuild the sandbox if needed`;
   const payload = {
     version: 1,
     status: 'failed',
     changed: false,
     lease: null,
-    error: { code, message: `${code}: controller request failed`, retryable: false }
+    error: { code, message, retryable: false }
   };
   return { exitCode: 1, stdout: `${JSON.stringify(payload)}\n`, stderr: '' };
 }
@@ -167,6 +207,17 @@ function orchestrationFailure(code: string, message: string): SandboxControlExec
   };
 }
 
+function lifecycleFailure(code: string, message: string): SandboxControlExecutionResult {
+  return {
+    exitCode: 1,
+    stdout: `${JSON.stringify({
+      status: 'failed', changed: false,
+      error: { code, message }
+    })}\n`,
+    stderr: ''
+  };
+}
+
 function finalizationResult(result: ReturnType<typeof applyTaskFinalization>): SandboxControlExecutionResult {
   const payload = {
     version: 1,
@@ -183,28 +234,17 @@ function finalizationResult(result: ReturnType<typeof applyTaskFinalization>): S
   };
 }
 
-function isCodexPrepare(args: readonly string[]): boolean {
-  if (args[1] !== 'prepare') return false;
-  const values: string[] = [];
-  for (let index = 2; index < args.length; index += 1) {
-    if (args[index] === '--client') values.push(args[index + 1] ?? '');
-    else if (args[index]?.startsWith('--client=')) values.push(args[index]!.slice('--client='.length));
-  }
-  return values.length === 1 && values[0] === 'codex';
-}
-
 type ExecuteRequestOptions = Readonly<{
   buildIdentity?: typeof computeLifecycleBuildIdentity;
   resolveControllerBinding?: typeof resolveCodexControllerBinding;
-  spawnDomain?: typeof spawnSync;
 }>;
 
-export function executeRequest(
+export async function executeRequest(
   manifest: SandboxControlManifest,
   manifestPath: string,
   request: SandboxControlRequest,
   options: ExecuteRequestOptions = {}
-): SandboxControlExecutionResult {
+): Promise<SandboxControlExecutionResult> {
   if (request.family === 'task-create') {
     const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
     return {
@@ -257,17 +297,47 @@ export function executeRequest(
     }
   }
   if (request.family === 'task-finalization') {
-    return finalizationResult(applyTaskFinalization(
-      { taskRef: manifest.taskId!, intent: 'complete', agent: request.agent },
-      { repoRoot: manifest.repoRoot, preflight: (input, options) => verifyTaskEvent(
-        { ...input, event: 'complete-task.hard-preflight' }, options
-      ) }
-    ));
+    const operation = parseTaskControlOperation(
+      'task-finalization', [manifest.taskId!, 'complete', '--agent', request.agent]
+    );
+    if (operation.family !== 'task-finalization') throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
+    const result = dispatchTaskControlOperation(
+      createSandboxExecutorExecutionContext({
+        repoRoot: manifest.repoRoot,
+        worktreeRoot: manifest.worktreeRoot,
+        runtimeDir: manifest.runtimeDir,
+        taskId: manifest.taskId!,
+        generation: manifest.generation,
+        manifestPath,
+        requestId: request.id
+      }),
+      operation
+    );
+    return finalizationResult(result);
   }
   const boundArgs = bindSandboxControlTask(request, manifest.taskId!);
-  let controllerBinding: Readonly<{ instanceDigest: string; controlGeneration: string }> | null = null;
   if (request.family === 'task-orchestration') {
-    if (isCodexPrepare(request.args)) {
+    boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
+  }
+  let operation: TaskControlOperation;
+  try {
+    operation = parseTaskControlOperation(request.family, boundArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'TASK_CONTROL_OPERATION_INVALID';
+    return request.family === 'task-lifecycle'
+      ? lifecycleFailure('LIFECYCLE_PAYLOAD_INVALID', message)
+      : orchestrationFailure(code, message);
+  }
+  let controllerBinding: Readonly<{
+    instanceDigest: string;
+    controlGeneration: string;
+  }> | null = null;
+  if (request.family === 'task-orchestration') {
+    const codexPrepare = operation.family === 'task-orchestration'
+      && operation.intent === 'prepare'
+      && operation.input.client === 'codex';
+    if (codexPrepare) {
       if (!request.controllerProof) {
         return orchestrationFailure(
           'CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED',
@@ -293,36 +363,69 @@ export function executeRequest(
         'Controller proof is only accepted for canonical Codex prepare'
       );
     }
-    boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
   }
-  const result = (options.spawnDomain ?? spawnSync)(
-    process.execPath,
-    nodeEntryArgs(process.argv[1]!, [request.family, ...boundArgs]),
-    {
-      cwd: manifest.repoRoot,
-      encoding: 'utf8',
-      env: {
-        ...safeEnv(process.env),
-        AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir,
-        ...(controllerBinding
-          ? { AGENT_INFRA_CONTROL_CONTROLLER_BINDING: JSON.stringify(controllerBinding) }
-          : {})
-      }
-    }
-  );
-  return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+  const context = createSandboxExecutorExecutionContext({
+    repoRoot: manifest.repoRoot,
+    worktreeRoot: manifest.worktreeRoot,
+    runtimeDir: manifest.runtimeDir,
+    taskId: manifest.taskId!,
+    generation: manifest.generation,
+    manifestPath,
+    requestId: request.id,
+    ...(controllerBinding ? { controllerBinding } : {})
+  });
+  const format = (value: unknown): SandboxControlExecutionResult => {
+    const result = value as { status?: string };
+    return {
+      exitCode: result.status === 'failed' ? 1 : 0,
+      stdout: `${JSON.stringify(value)}\n`,
+      stderr: ''
+    };
+  };
+  if (request.family === 'task-orchestration') {
+    if (operation.family !== 'task-orchestration') throw new Error('SANDBOX_CONTROL_ORCHESTRATION_OPERATION_INVALID');
+    return format(await dispatchTaskControlOperation(context, operation));
+  }
+  if (operation.family !== 'task-lifecycle') throw new Error('SANDBOX_CONTROL_LIFECYCLE_OPERATION_INVALID');
+  return format(dispatchTaskControlOperation(context, operation));
 }
 
 export async function runSandboxControlExecutor(requestPath: string, nonce: string): Promise<void> {
-  await waitForGate(nonce);
+  const gateOwner = await waitForGate(nonce);
   process.disconnect?.();
-  const root = fs.realpathSync.native(process.cwd());
-  const request = JSON.parse(fs.readFileSync(requestPath, 'utf8')) as SandboxControlRequest;
   const manifestPath = process.env.AGENT_INFRA_EXECUTOR_MANIFEST;
   if (!manifestPath) throw new Error('SANDBOX_CONTROL_EXECUTOR_MANIFEST_MISSING');
-  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as SandboxControlManifest;
+  const manifest = readSandboxControlManifest(manifestPath);
+  const root = fs.realpathSync.native(process.cwd());
   if (fs.realpathSync.native(manifest.repoRoot) !== root) throw new Error('SANDBOX_CONTROL_EXECUTOR_ROOT_INVALID');
-  const result = executeRequest(manifest, manifestPath, request);
+  const raw = JSON.parse(fs.readFileSync(requestPath, 'utf8')) as unknown;
+  const request = validateSandboxControlRequest(raw, manifest);
+  const requestDirectory = path.resolve(path.dirname(requestPath));
+  const processingDirectory = path.resolve(path.join(manifest.processingDir, request.id));
+  const channelRequestDirectory = path.resolve(path.join(manifest.channelDir, 'requests'));
+  if (requestDirectory !== processingDirectory && requestDirectory !== channelRequestDirectory) {
+    throw new Error('SANDBOX_CONTROL_EXECUTOR_REQUEST_INVALID');
+  }
+  let result: SandboxControlExecutionResult;
+  try {
+    assertSandboxControlExecutorAuthority(manifest, gateOwner);
+    result = await executeRequest(manifest, manifestPath, request);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/u.exec(detail)?.[1] ?? 'SANDBOX_CONTROL_EXECUTOR_FAILED';
+    result = request.family === 'task-finalization'
+      ? {
+        exitCode: 1,
+        stdout: `${JSON.stringify({
+          version: 1, status: 'failed', changed: false, accepted: true, result: null,
+          error: { code, message: detail, retryable: false }
+        })}\n`,
+        stderr: ''
+      }
+      : request.family === 'task-lifecycle'
+        ? lifecycleFailure(code, detail)
+        : orchestrationFailure(code, detail);
+  }
   process.stdout.write(result.stdout);
   process.stderr.write(result.stderr);
   process.exitCode = result.exitCode;

package/lib/sandbox/control/lifecycle.ts

@@ -10,9 +10,7 @@ import {
 import type { ProcessIdentity, ProcessIdentityProbe, ProcessIdentityState } from '../../server/process-state.ts';
 import type {
   SandboxControlExecution,
-  SandboxControlManifestLike,
   SandboxControlManifest,
-  SandboxControlLegacyManifest,
   SandboxControlStatus,
   SandboxControlTimingPolicy
 } from './protocol.ts';
@@ -468,7 +466,6 @@ function readProcessingSnapshot(root: string): SandboxControlCutoverSnapshot['pr
 export function captureSandboxControlCutoverSnapshot(root: string): SandboxControlCutoverSnapshot {
   const resolvedRoot = path.resolve(root);
   const manifestPath = path.join(resolvedRoot, 'manifest.json');
-  if (fs.existsSync(manifestPath)) readSandboxControlManifestForTransition(manifestPath);
   return {
     root: resolvedRoot,
     manifestRaw: readOptionalRaw(manifestPath),
@@ -485,10 +482,7 @@ export function assertSandboxControlCutoverSnapshot(snapshot: SandboxControlCuto
   }
 }
 
-function readSandboxControlManifestValue(
-  manifestPath: string,
-  allowLegacy: boolean
-): SandboxControlManifestLike {
+function readSandboxControlManifestValue(manifestPath: string): SandboxControlManifest {
   if (!regularFile(manifestPath)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   let manifest: Record<string, unknown>;
   try {
@@ -500,9 +494,15 @@ function readSandboxControlManifestValue(
   } catch {
     throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   }
-  const candidate = manifest as Partial<SandboxControlManifest> & Partial<SandboxControlLegacyManifest>;
-  if (candidate.version !== 4 && candidate.version !== 5) {
-    throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 5; container-only recreation is required');
+  const candidate = manifest as Partial<SandboxControlManifest> & { version?: unknown };
+  const expectedKeys = [
+    'branch', 'channelDir', 'container', 'containerIdentity', 'engine', 'generation',
+    'mode', 'processingDir', 'project', 'publicStatusDir', 'repoRoot', 'runtimeDir',
+    'taskId', 'token', 'worktreeRoot'
+  ];
+  if ('version' in candidate || typeof candidate.runtimeDir !== 'string'
+    || Object.keys(manifest).sort().join(',') !== expectedKeys.sort().join(',')) {
+    throw new Error('SANDBOX_CONTROL_MANIFEST_REBUILD_REQUIRED: container-only recreation/rebuild is required');
   }
   if (typeof candidate.containerIdentity !== 'object' || candidate.containerIdentity === null
     || Array.isArray(candidate.containerIdentity)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
@@ -518,31 +518,23 @@ function readSandboxControlManifestValue(
     || (candidate.taskId !== null && typeof candidate.taskId !== 'string')
     || typeof candidate.channelDir !== 'string' || typeof candidate.publicStatusDir !== 'string'
     || typeof candidate.processingDir !== 'string' || typeof candidate.token !== 'string'
-    || typeof candidate.generation !== 'string') throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    || typeof candidate.generation !== 'string'
+    || (candidate.mode === 'task-bound' && (typeof candidate.taskId !== 'string' || candidate.taskId.length === 0))
+    || (candidate.mode === 'branch-only' && candidate.taskId !== null)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   const root = path.dirname(path.resolve(manifestPath));
   if (path.resolve(candidate.channelDir) !== path.join(root, 'channel')
     || path.resolve(candidate.publicStatusDir) !== path.join(root, 'public')
     || path.resolve(candidate.processingDir) !== path.join(root, 'processing')) {
     throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   }
-  if (candidate.version === 4) {
-    if (!allowLegacy) {
-      throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 5; container-only recreation is required');
-    }
-    return candidate as unknown as SandboxControlLegacyManifest;
-  }
-  if (typeof candidate.runtimeDir !== 'string' || path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
+  if (path.resolve(candidate.runtimeDir) !== path.join(root, 'runtime')) {
     throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
   }
-  return candidate as unknown as SandboxControlManifest;
+  return candidate as SandboxControlManifest;
 }
 
 export function readSandboxControlManifest(manifestPath: string): SandboxControlManifest {
-  return readSandboxControlManifestValue(manifestPath, false) as SandboxControlManifest;
-}
-
-export function readSandboxControlManifestForTransition(manifestPath: string): SandboxControlManifestLike {
-  return readSandboxControlManifestValue(manifestPath, true);
+  return readSandboxControlManifestValue(manifestPath);
 }
 
 function readBrokerOwner(filePath: string): BrokerOwner | null {
@@ -561,6 +553,20 @@ function readBrokerOwner(filePath: string): BrokerOwner | null {
   return owner as BrokerOwner;
 }
 
+export function assertSandboxControlBrokerOwner(
+  manifest: SandboxControlManifest,
+  options: Readonly<{ identityProbe?: ProcessIdentityProbe }> = {}
+): BrokerOwner {
+  const root = path.dirname(path.resolve(manifest.publicStatusDir));
+  const owner = readBrokerOwner(path.join(root, 'broker.json'));
+  if (!owner) throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
+  if (owner.token !== manifest.token || owner.generation !== manifest.generation) {
+    throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  }
+  if (!ownerLive(owner, options.identityProbe)) throw new Error('SANDBOX_CONTROL_OWNER_LOST');
+  return owner;
+}
+
 function readStatusOwner(filePath: string): SandboxControlStatus | null {
   if (!fs.existsSync(filePath)) return null;
   if (!regularFile(filePath)) throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
@@ -585,7 +591,7 @@ function ownerLive(
   return state === 'alive';
 }
 
-function readExecutions(manifest: SandboxControlManifestLike): SandboxControlExecution[] {
+function readExecutions(manifest: SandboxControlManifest): SandboxControlExecution[] {
   if (!fs.existsSync(manifest.processingDir)) return [];
   const stat = fs.lstatSync(manifest.processingDir);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
@@ -705,7 +711,7 @@ export async function quiesceSandboxControlRoot(
   await waitForStartupTransition(resolvedRoot, Math.max(0, forceAt - Date.now()), identityProbe);
 
   const manifestPath = path.join(resolvedRoot, 'manifest.json');
-  const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifestForTransition(manifestPath) : null;
+  const manifest = fs.existsSync(manifestPath) ? readSandboxControlManifest(manifestPath) : null;
   const broker = readBrokerOwner(path.join(resolvedRoot, 'broker.json'));
   const status = readStatusOwner(path.join(resolvedRoot, 'public', 'status.json'));
   const statusOwner = status ? status.broker : null;
@@ -799,7 +805,7 @@ export async function removeSandboxControlRoot(
   const stat = fs.lstatSync(resolvedRoot);
   if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
   const manifestPath = path.join(resolvedRoot, 'manifest.json');
-  const manifest = readSandboxControlManifestForTransition(manifestPath);
+  const manifest = readSandboxControlManifest(manifestPath);
   const inspectContainer = options.inspectContainer
     ?? ((timeoutMs) => inspectSandboxControlContainer(manifest, { timeoutMs }));
   const timeoutMs = options.timeoutMs ?? options.timing?.quiesceDeadlineMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
@@ -870,7 +876,7 @@ export async function removeSandboxControlRoot(
     }
   }
 
-  const currentManifest = readSandboxControlManifestForTransition(manifestPath);
+  const currentManifest = readSandboxControlManifest(manifestPath);
   if (currentManifest.token !== manifest.token || currentManifest.generation !== manifest.generation
     || !isSandboxControlRootQuiescing(resolvedRoot)) {
     throw new Error('SANDBOX_CONTROL_OWNER_TRANSITION');

package/lib/sandbox/control/protocol.ts

@@ -35,9 +35,7 @@ export type SandboxControlManifestBase = Readonly<{
   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 SandboxControlManifest = SandboxControlManifestBase & Readonly<{ runtimeDir: string }>;
 export type SandboxControlBrokerOwner = ProcessIdentity & Readonly<{
   version: 3;
   brokerId: string;