@fitlab-ai/agent-infra 0.11.11 → 0.11.13

package/lib/platform/github-client.ts

@@ -51,6 +51,33 @@ function boundedFailureDetail(result: RunResult): string {
     : `${diagnostic.slice(0, ERROR_DETAIL_LIMIT)}… [truncated]`;
 }
 
+function requestDiagnostics(args: string[], request: RequestOptions, attempt: number, errorMessage: string): string {
+  if (process.env.AGENT_INFRA_GH_DIAGNOSTICS !== '1' && !/rate.?limit/iu.test(errorMessage)) return '';
+
+  const apiIndex = args.indexOf('api');
+  const endpoint = apiIndex < 0
+    ? args.slice(0, 2).filter((arg) => !arg.startsWith('-')).join(' ')
+    : args.slice(apiIndex + 1).find((arg) => !arg.startsWith('-') && !arg.includes('=')) || 'unknown';
+  const safeEndpoint = endpoint.startsWith('http')
+    ? (() => {
+      try {
+        const url = new URL(endpoint);
+        return `${url.host}${url.pathname}`;
+      } catch {
+        return 'unknown';
+      }
+    })()
+    : endpoint.split('?')[0] || 'unknown';
+  const methodIndex = args.findIndex((arg) => arg === '-X' || arg === '--method');
+  const methodFromArgs = methodIndex >= 0 ? args[methodIndex + 1] : undefined;
+  const method = methodFromArgs || request.method || (safeEndpoint === 'graphql' ? 'POST' : 'GET');
+  const tokenEnvironment = ['GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN']
+    .filter((name) => Boolean(process.env[name]));
+  const configDirOverride = Boolean(process.env.GH_CONFIG_DIR);
+
+  return ` [gh-diagnostic endpoint=${safeEndpoint} method=${method} attempt=${attempt} tokenEnv=${tokenEnvironment.join(',') || 'none'} ghConfigDirOverride=${configDirOverride}]`;
+}
+
 function defaultRunner(args: string[], options: RunOptions): RunResult {
   const command = process.env.AGENT_INFRA_GH_BIN || 'gh';
   let prefix: string[] = [];
@@ -168,13 +195,17 @@ function createGitHubClient(options: ClientOptions = {}): GitHubClient {
       const result = runner(args, request);
       if (result.status === 0) return { ok: true, value: result.stdout };
       const error = classifyGitHubFailure(result);
-      if (!retryableMethod || !error.requestRetryable) return { ok: false, error: clientError(error) };
+      const requestDetail = requestDiagnostics(args, request, attempt + 1, error.message);
+      const contextualError = requestDetail
+        ? { ...error, message: `${error.message}${requestDetail}` }
+        : error;
+      if (!retryableMethod || !error.requestRetryable) return { ok: false, error: clientError(contextualError) };
       if (attempt >= delays.length) {
         return {
           ok: false,
           error: error.code === 'NETWORK_TRANSIENT'
-            ? { ...clientError(error), code: 'NETWORK_RETRY_EXHAUSTED', message: `${error.message} (retry exhausted)` }
-            : clientError(error)
+            ? { ...clientError(contextualError), code: 'NETWORK_RETRY_EXHAUSTED', message: `${contextualError.message} (retry exhausted)` }
+            : clientError(contextualError)
         };
       }
       sleep(delays[attempt]!);

package/lib/platform/issues.ts

@@ -516,7 +516,8 @@ async function syncPlatformIssueImpl(taskRef: string, options: SyncOptions): Pro
   let providerMetadata: RepositoryMetadataSnapshot | null = null;
   let repositoryLabels: string[] = [];
   let milestones: string[] = [];
-  if (base.context.capabilities.triage && (options.status !== undefined || options.inLabels !== undefined || options.milestone !== undefined || options.issueType || options.fields)) {
+  if (base.context.capabilities.triage && (options.status !== undefined || options.inLabels !== undefined || options.milestone !== undefined
+    || (base.context.capabilities.push && (options.issueType || options.fields)))) {
     const metadata = base.provider.issues?.describeRepository
       ? await base.provider.issues.describeRepository({ context: providerOperationContext(base.loadedContext) })
       : unsupportedProviderOperation(base.provider, 'issues.describeRepository');
@@ -592,15 +593,26 @@ async function syncPlatformIssueImpl(taskRef: string, options: SyncOptions): Pro
     }
   }
   if (options.issueType || options.fields) {
-    plan.operations.push(...(providerMetadata
-      ? planProviderMetadata(inspected.value, providerMetadata, base.frontmatter, options, base.context.capabilities)
-      : [{ name: 'issue-type', status: 'skipped' as const, reasonCode: 'ISSUE_TYPES_UNSUPPORTED' }]));
+    plan.operations.push(...(!base.context.capabilities.push
+      ? [
+        ...(options.issueType ? [{ name: 'issue-type', status: 'skipped' as const, reasonCode: 'PUSH_REQUIRED' }] : []),
+        ...(options.fields ? [{ name: 'fields', status: 'skipped' as const, reasonCode: 'PUSH_REQUIRED' }] : [])
+      ]
+      : providerMetadata
+        ? planProviderMetadata(inspected.value, providerMetadata, base.frontmatter, options, base.context.capabilities)
+        : [{ name: 'issue-type', status: 'skipped' as const, reasonCode: 'ISSUE_TYPES_UNSUPPORTED' }]));
   }
   const failure = plan.operations.find((operation) => operation.status === 'failed');
   if (failure) return result('failed', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: { code: failure.reasonCode || 'ISSUE_SYNC_FAILED', message: `Operation ${failure.name} failed`, retryable: false } });
   const planned = plan.operations.filter((operation) => operation.status === 'planned');
-  if (options.dryRun) return result(planned.length ? 'planned' : 'no-op', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: null });
-  if (planned.length === 0) return result('no-op', base.resolved.taskId, base.issueNumber, { issue: snapshot, operations: plan.operations, error: null });
+  if (options.dryRun) return result(planned.length ? 'planned' : 'no-op', base.resolved.taskId, base.issueNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    issue: snapshot, operations: plan.operations, error: null
+  });
+  if (planned.length === 0) return result('no-op', base.resolved.taskId, base.issueNumber, {
+    platform: base.context.platform, capabilities: base.context.capabilities,
+    issue: snapshot, operations: plan.operations, error: null
+  });
   const payload = applyRestOperations(snapshot, planned) as Partial<{
     title: string; body: string; labels: string[]; assignees: string[];
     milestone: string | null; state: 'open' | 'closed'; fields: Record<string, string | number | null>;

package/lib/runtime/agent-runtime.ts

@@ -1,16 +1,5 @@
 import path from 'node:path';
-
-export type AgentRuntimeStore = 'capabilities' | 'lifecycle';
-
-type RuntimeResolutionOptions = Readonly<{
-  repoRoot?: string;
-  env?: NodeJS.ProcessEnv;
-  explicitRoot?: string;
-  client?: string;
-  store?: AgentRuntimeStore;
-}>;
-
-const CLIENT_NAMESPACE = /^[a-z][a-z0-9-]{0,31}$/u;
+import { resolveTaskRuntimeRoot } from '../task/runtime-paths.ts';
 
 function runtimeError(code: string, message: string): Error {
   const error = new Error(`${code}: ${message}`);
@@ -22,18 +11,10 @@ function boundControlContext(env: NodeJS.ProcessEnv): boolean {
   return [
     'AGENT_INFRA_CONTROL_TOKEN',
     'AGENT_INFRA_CONTROL_GENERATION',
-    'AGENT_INFRA_EXECUTOR_MANIFEST',
-    'AGENT_INFRA_CODEX_CONTROLLER_CONTEXT'
+    'AGENT_INFRA_EXECUTOR_MANIFEST'
   ].some((key) => typeof env[key] === 'string' && env[key]!.length > 0);
 }
 
-function clientNamespace(client: string): string {
-  if (!CLIENT_NAMESPACE.test(client)) {
-    throw runtimeError('AGENT_INFRA_RUNTIME_CLIENT_INVALID', `invalid runtime client namespace '${client}'`);
-  }
-  return client;
-}
-
 export function resolveAgentRuntimeRoot(options: Readonly<{
   repoRoot?: string;
   env?: NodeJS.ProcessEnv;
@@ -46,6 +27,10 @@ export function resolveAgentRuntimeRoot(options: Readonly<{
     }
     return path.resolve(configured);
   }
+  const taskId = env.AGENT_INFRA_TASK_ID;
+  if (taskId) {
+    return resolveTaskRuntimeRoot(taskId, { repoRoot: options.repoRoot });
+  }
   if (boundControlContext(env)) {
     throw runtimeError(
       'AGENT_INFRA_RUNTIME_DIR_REQUIRED',
@@ -54,23 +39,3 @@ export function resolveAgentRuntimeRoot(options: Readonly<{
   }
   return path.join(path.resolve(options.repoRoot ?? process.cwd()), '.agents', 'workspace', '.runtime');
 }
-
-export function resolveAgentRuntimeStoreRoot(options: RuntimeResolutionOptions = {}): string {
-  const client = clientNamespace(options.client ?? 'codex');
-  if (options.explicitRoot) return path.resolve(options.explicitRoot);
-  const env = options.env ?? process.env;
-  const runtimeRoot = resolveAgentRuntimeRoot({ repoRoot: options.repoRoot, env });
-  if (env.AGENT_INFRA_RUNTIME_DIR) {
-    if (!options.store) {
-      throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required for task-bound runtime');
-    }
-    return path.join(runtimeRoot, 'clients', client, options.store);
-  }
-  if (client === 'codex' && options.store) {
-    return path.join(runtimeRoot, `codex-${options.store}`);
-  }
-  if (!options.store) {
-    throw runtimeError('AGENT_INFRA_RUNTIME_STORE_INVALID', 'store kind is required');
-  }
-  return path.join(runtimeRoot, 'clients', client, options.store);
-}

package/lib/sandbox/commands/control-status.ts

@@ -14,6 +14,7 @@ export function readSandboxControlStatusForRow(
     : { mode: 'branch-only' as const };
   const control = sandboxControlPaths({
     base: config.controlBase,
+    repoRoot: config.repoRoot,
     project: config.project,
     container: row.name,
     identity

package/lib/sandbox/commands/create.ts

@@ -91,6 +91,7 @@ import {
   materializeSandboxControl,
   materializeSandboxWorkspaceView,
   prepareSandboxWorkspaceMountTargets,
+  prepareSandboxCompletedTaskMountSource,
   sandboxControlPaths,
 } from '../workspace-view.ts';
 import { clipboardHostDir, CONTAINER_CLIPBOARD_MOUNT } from '../clipboard/paths.ts';
@@ -1107,6 +1108,7 @@ export async function create(
   const container = containerName(effectiveConfig, branch);
   const controlPaths = sandboxControlPaths({
     base: effectiveConfig.controlBase,
+    repoRoot: effectiveConfig.repoRoot,
     project: effectiveConfig.project,
     container,
     identity: target.workspace
@@ -1450,7 +1452,10 @@ export async function create(
             const taskSource = target.workspace.mode === 'task-bound'
               ? assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId)
               : null;
-            prepareSandboxWorkspaceMountTargets(worktree);
+            const completedTaskSource = target.workspace.mode === 'task-bound'
+              ? prepareSandboxCompletedTaskMountSource(effectiveConfig.repoRoot, target.workspace.taskId)
+              : null;
+            prepareSandboxWorkspaceMountTargets(worktree, target.workspace.mode === 'task-bound' ? target.workspace.taskId : undefined);
             if (previousCutoverSnapshot) {
               assertSandboxControlCutoverSnapshot(previousCutoverSnapshot);
               if (previousManifest) {
@@ -1493,6 +1498,7 @@ export async function create(
               ...(target.workspace.mode === 'task-bound'
                 ? {
                   taskSources: [taskSource!],
+                  completedTaskSource: completedTaskSource!,
                   taskId: target.workspace.taskId
                 }
                 : {})

package/lib/sandbox/commands/ls.ts

@@ -18,11 +18,10 @@ export { containerListFormat, parseLabels } from './list-running.ts';
 const USAGE = `Usage: ai sandbox ls
 
 Lists all containers for the current project. The '#' column is a
-display-only row number; the 'SHORT' column shows the active task short
-id bound to each container's branch (via
-.agents/workspace/active/.short-ids.json), or '-' if no active task is
-bound. Pass the SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
-A SHORT value of '-' means this container has no active task short id and may
+display-only row number; the 'SHORT' column shows the task short id bound to
+each task-bound container, or '-' if no short id is registered. Pass the
+SHORT value to "ai sandbox exec" (e.g. 'ai sandbox exec 11').
+A SHORT value of '-' means this container has no task short id and may
 be eligible for "ai sandbox rm --unbound" cleanup. Use a full TASK-id to
 remove a specific task-bound sandbox.
 

package/lib/sandbox/commands/rm.ts

@@ -13,7 +13,7 @@ import { fetchSandboxRows } from './list-running.ts';
 import { rmOne, rmPurge, rmUnbound } from '../removal.ts';
 
 const USAGE = `Usage:
-  ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
+  ai sandbox rm <branch | TASK-id | short id> Remove one sandbox; use a retained short id or full TASK-id for a task-bound sandbox and a branch for branch-only sandboxes
   ai sandbox rm --unbound [--dry-run] [--yes] Remove sandboxes not bound to an active task short id
   ai sandbox rm --purge                     Tear down ALL sandboxes for the project (containers, worktrees, image, VM)`;
 

package/lib/sandbox/control/agent-operation.ts

@@ -0,0 +1,49 @@
+import { getAgentClientAdapter } from '../../agent-clients/registry.ts';
+import type { AgentClientSandboxControlOperation } from '../../agent-clients/adapter.ts';
+import type { SandboxControlManifest, SandboxAgentClientRequest } from './protocol.ts';
+
+function operationFor(request: SandboxAgentClientRequest) {
+  const adapter = getAgentClientAdapter(request.agentClient);
+  const operation = adapter.sandboxControlOperation;
+  if (!operation) throw new Error('SANDBOX_CONTROL_AGENT_OPERATION_UNSUPPORTED');
+  return operation;
+}
+
+function validateAgentClientOperation(request: SandboxAgentClientRequest, manifest: SandboxControlManifest): void {
+  operationFor(request).validate({
+    operation: request.operation,
+    payload: request.payload,
+    manifest
+  });
+}
+
+function executeAgentClientOperation(
+  request: SandboxAgentClientRequest,
+  manifest: SandboxControlManifest,
+  manifestPath: string,
+  override?: AgentClientSandboxControlOperation
+) {
+  return (override ?? operationFor(request)).execute({
+    operation: request.operation,
+    payload: request.payload,
+    manifest,
+    manifestPath
+  });
+}
+
+function recoverAgentClientOperation(params: Readonly<{
+  request: SandboxAgentClientRequest;
+  manifest: SandboxControlManifest;
+  manifestPath: string;
+  stdout: string | null;
+}>): Readonly<Record<string, unknown>> {
+  const operation = operationFor(params.request);
+  return operation.recover?.({
+    operation: params.request.operation,
+    manifest: params.manifest,
+    manifestPath: params.manifestPath,
+    stdout: params.stdout
+  }) ?? { consistent: false };
+}
+
+export { executeAgentClientOperation, recoverAgentClientOperation, validateAgentClientOperation };

package/lib/sandbox/control/client.ts

@@ -9,16 +9,10 @@ import {
   type SandboxControlError,
   type SandboxControlRequest,
   type SandboxControlResponse,
-  type SandboxTaskCreateRequest,
-  type SandboxTaskFinalizationRequest,
-  type SandboxCodexControllerRequest
+  type SandboxAgentClientRequest,
+  type SandboxTaskCreateRequest
 } from './protocol.ts';
-import type {
-  CodexControllerLeaseProofV1,
-  CodexControllerOpened
-} from './controller-registration.ts';
-import type { ProcessIdentity } from '../../server/process-state.ts';
-import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
+import { isAgentClientId } from '../../agent-clients/types.ts';
 import { readSandboxControlPayload, readSandboxControlStatus } from './state.ts';
 import type { TaskCreateCandidateV1 } from '../../task/create.ts';
 import { accessSandboxTaskView, taskViewFromStatus, type TaskViewAccessEffect } from './task-view.ts';
@@ -29,7 +23,6 @@ import { loadConfig } from '../config.ts';
 import { recoverSandboxControlFromHost } from './host-recovery.ts';
 
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
-const SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS = 5 * 60_000;
 
 export class SandboxControlClientError extends Error {
   readonly detail: SandboxControlError;
@@ -118,7 +111,6 @@ function preflight(
 
 function taskViewEffectForRequest(request: SandboxControlRequest): TaskViewAccessEffect | null {
   if (request.family === 'task-lifecycle') return 'progress';
-  if (request.family === 'task-finalization') return 'recovery';
   return null;
 }
 
@@ -220,9 +212,6 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
         || (requestTask.kind === 'task' && requestTask.taskId !== identity.taskId))) {
       clientError('SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH', 'request task does not match the sandbox identity', false);
     }
-    if (identity.mode === 'branch-only' && request.family === 'task-finalization') {
-      clientError('SANDBOX_CONTROL_BRANCH_ONLY', 'branch-only sandboxes cannot finalize tasks', false);
-    }
   }
   const encoded = `${JSON.stringify(request)}\n`;
   if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
@@ -425,270 +414,49 @@ export function requestSandboxControl(params: Readonly<{
   token?: string; generation?: string; timeoutMs?: number;
 }>): SandboxControlResponse {
   if (!isSandboxControlFamily(params.family)) clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' is not allowed`, false);
-  if (params.family === 'task-create' || params.family === 'codex-controller' || params.family === 'task-finalization') {
+  if (params.family === 'task-create' || params.family === 'agent-client') {
     clientError('SANDBOX_CONTROL_COMMAND_DENIED', `'${params.family}' requires a typed request`, false);
   }
+  if (params.args[1] === 'complete') {
+    clientError('SANDBOX_CONTROL_COMMAND_DENIED', 'complete must use task-finalization', false);
+  }
   const auth = authority(params);
   const issuedAt = Date.now();
   const request: SandboxControlRequest = {
     version: 4, id: randomUUID(), ...auth, issuedAt,
     expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-    family: params.family as 'task-lifecycle', args: params.args,
-    controllerProcess: null,
-    controllerProof: null
+    family: params.family as 'task-lifecycle', args: params.args
   };
   return exchangeSandboxControl(request, params);
 }
 
-export function requestSandboxTaskFinalization(params: Readonly<{
-  agent: string;
+export function requestSandboxAgentOperation(params: Readonly<{
+  agentClient: string;
+  operation: string;
+  payload: Record<string, unknown>;
   channelDir?: string;
   statusDir?: string;
   token?: string;
   generation?: string;
   timeoutMs?: number;
-  recoveryBudgetMs?: number;
 }>): SandboxControlResponse {
-  const agent = normalizeAgentToken(params.agent);
-  if (!agent) clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization agent is invalid', false);
-  const auth = authority(params);
-  const issuedAt = Date.now();
-  const id = randomUUID();
-  const request: SandboxTaskFinalizationRequest = {
-    version: 4,
-    id,
-    ...auth,
-    issuedAt,
-    expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-    family: 'task-finalization',
-    operation: 'complete',
-    agent,
-    args: [],
-    controllerProcess: null,
-    controllerProof: null
-  };
-  let response: SandboxControlResponse;
-  try {
-    response = exchangeSandboxControl(request, params);
-  } catch (error) {
-    if (!(error instanceof SandboxControlClientError)
-      || error.detail.code !== 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-      || !error.accepted || !error.requestId) throw error;
-    return recoverAcceptedTaskFinalization(error.requestId, params);
-  }
-  if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
-    return recoverAcceptedTaskFinalization(response.id, params);
-  }
-  return response;
-}
-
-export function recoverAcceptedTaskFinalization(
-  requestId: string,
-  params: Readonly<{ recoveryBudgetMs?: number }>,
-  recover: typeof recoverSandboxControl = recoverSandboxControl
-): SandboxControlResponse {
-  const deadline = Date.now() + (params.recoveryBudgetMs ?? SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS);
-  while (Date.now() < deadline) {
-    const timeoutMs = Math.min(30_000, deadline - Date.now());
-    if (timeoutMs <= 0) break;
-    try {
-      const response = recover(requestId, { timeoutMs });
-      if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') continue;
-      return response;
-    } catch (error) {
-      if (error instanceof SandboxControlClientError
-        && error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-        && error.requestId === requestId) continue;
-      throw error;
-    }
+  if (!isAgentClientId(params.agentClient)) {
+    clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'agent-client id is invalid', false);
   }
-  clientError(
-    'SANDBOX_CONTROL_RESULT_UNKNOWN',
-    'accepted finalization request remained unknown after the automatic recovery budget; inspect the receipt and resume by request id',
-    false,
-    true,
-    requestId
-  );
-}
-
-type CodexControllerClosed = Readonly<{
-  version: 1;
-  status: 'closed';
-  changed: boolean;
-  lease: null;
-  error: null;
-}>;
-
-type CodexControllerVerified = Readonly<{
-  version: 1;
-  status: 'verified';
-  changed: false;
-  lease: null;
-  binding: Readonly<{
-    taskId: string;
-    controlGeneration: string;
-    controllerInstanceDigest: string;
-  }>;
-  error: null;
-}>;
-
-function exactKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
-  return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
-}
-
-function validProcess(value: unknown): value is ProcessIdentity {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  const identity = value as Record<string, unknown>;
-  return exactKeys(identity, ['pid', 'startTime'])
-    && Number.isSafeInteger(identity.pid) && (identity.pid as number) > 0
-    && Number.isSafeInteger(identity.startTime) && (identity.startTime as number) >= 0;
-}
-
-function validBuild(value: unknown): boolean {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
-  const build = value as Record<string, unknown>;
-  return exactKeys(build, ['internalExecutableBuildHash', 'lifecycleContractHash', 'packageVersion', 'protocolVersion'])
-    && build.protocolVersion === 3
-    && typeof build.packageVersion === 'string' && build.packageVersion.length > 0
-    && typeof build.internalExecutableBuildHash === 'string' && /^[a-f0-9]{64}$/u.test(build.internalExecutableBuildHash)
-    && typeof build.lifecycleContractHash === 'string' && /^[a-f0-9]{64}$/u.test(build.lifecycleContractHash);
-}
-
-export function parseCodexControllerResult(response: SandboxControlResponse): CodexControllerOpened | CodexControllerClosed | CodexControllerVerified {
-  if (response.phase !== 'completed' || response.error !== null || response.stderr !== '') {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result outer response is invalid', false, true);
-  }
-  let value: unknown;
-  try {
-    if (!response.stdout.endsWith('\n') || response.stdout.slice(0, -1).includes('\n')) throw new Error('not canonical');
-    value = JSON.parse(response.stdout);
-  } catch {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result payload is invalid', false, true);
-  }
-  if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result payload is invalid', false, true);
-  }
-  const result = value as Record<string, unknown>;
-  const resultKeys = result.status === 'verified'
-    ? ['binding', 'changed', 'error', 'lease', 'status', 'version']
-    : ['changed', 'error', 'lease', 'status', 'version'];
-  if (!exactKeys(result, resultKeys)
-    || result.version !== 1 || !['opened', 'closed', 'failed', 'verified'].includes(result.status as string)) {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result schema is invalid', false, true);
-  }
-  if (result.status === 'failed') {
-    const error = result.error as { code?: unknown; message?: unknown; retryable?: unknown } | null;
-    if (response.exitCode !== 1 || result.changed !== false || result.lease !== null
-      || !error || !exactKeys(error as Record<string, unknown>, ['code', 'message', 'retryable'])
-      || typeof error.code !== 'string' || !/^[A-Z][A-Z0-9_]+$/u.test(error.code)
-      || typeof error.message !== 'string' || error.retryable !== false) {
-      clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller failure result is invalid', false, true);
-    }
-    clientError(error.code, error.message, false, true);
-  }
-  if (response.exitCode !== 0 || result.error !== null) {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller success result is invalid', false, true);
-  }
-  if (result.status === 'closed') {
-    if (typeof result.changed !== 'boolean' || result.lease !== null) {
-      clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller close result is invalid', false, true);
-    }
-    return result as unknown as CodexControllerClosed;
-  }
-  if (result.status === 'verified') {
-    const binding = result.binding as Record<string, unknown> | null;
-    if (result.changed !== false || result.lease !== null || !binding
-      || !exactKeys(binding, ['controllerInstanceDigest', 'controlGeneration', 'taskId'])
-      || typeof binding.taskId !== 'string' || binding.taskId.length === 0
-      || typeof binding.controlGeneration !== 'string' || binding.controlGeneration.length === 0
-      || typeof binding.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(binding.controllerInstanceDigest)) {
-      clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller verify result is invalid', false, true);
-    }
-    return result as unknown as CodexControllerVerified;
-  }
-  const lease = result.lease as Record<string, unknown> | null;
-  if (result.changed !== true || !lease
-    || !exactKeys(lease, [
-      'buildIdentity', 'controlGeneration', 'controllerInstanceDigest', 'controllerProcess',
-      'expiresAt', 'issuedAt', 'leaseId', 'leaseSecret', 'taskId', 'version'
-    ])
-    || lease.version !== 1
-    || typeof lease.leaseId !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.leaseId)
-    || typeof lease.leaseSecret !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.leaseSecret)
-    || typeof lease.taskId !== 'string' || lease.taskId.length === 0
-    || typeof lease.controlGeneration !== 'string' || lease.controlGeneration.length === 0
-    || typeof lease.controllerInstanceDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(lease.controllerInstanceDigest)
-    || !validProcess(lease.controllerProcess) || !validBuild(lease.buildIdentity)
-    || !Number.isSafeInteger(lease.issuedAt) || !Number.isSafeInteger(lease.expiresAt)
-    || (lease.expiresAt as number) <= (lease.issuedAt as number)) {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller open result is invalid', false, true);
-  }
-  return result as unknown as CodexControllerOpened | CodexControllerClosed;
-}
-
-function requestCodexController(params: Readonly<{
-  command: 'open' | 'close' | 'verify';
-  controllerProcess: ProcessIdentity;
-  controllerProof: CodexControllerLeaseProofV1 | null;
-  channelDir?: string;
-  statusDir?: string;
-  token?: string;
-  generation?: string;
-  timeoutMs?: number;
-}>): CodexControllerOpened | CodexControllerClosed | CodexControllerVerified {
   const auth = authority(params);
   const issuedAt = Date.now();
-  const request: SandboxCodexControllerRequest = {
+  const request: SandboxAgentClientRequest = {
     version: 4,
     id: randomUUID(),
     ...auth,
     issuedAt,
     expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
-    family: 'codex-controller',
-    command: params.command,
-    args: [],
-    controllerProcess: params.controllerProcess,
-    controllerProof: params.controllerProof
+    family: 'agent-client',
+    agentClient: params.agentClient,
+    operation: params.operation,
+    payload: params.payload
   };
-  const result = parseCodexControllerResult(exchangeSandboxControl(request, params));
-  if (result.status === 'opened'
-    && (result.lease.controlGeneration !== auth.generation
-      || result.lease.controllerProcess.pid !== params.controllerProcess.pid
-      || result.lease.controllerProcess.startTime !== params.controllerProcess.startTime)) {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller result does not match the request', false, true);
-  }
-  return result;
-}
-
-export function requestCodexControllerOpen(params: Omit<Parameters<typeof requestCodexController>[0], 'command' | 'controllerProof'>): CodexControllerOpened {
-  const result = requestCodexController({ ...params, command: 'open', controllerProof: null });
-  if (result.status !== 'opened') clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller open returned the wrong result', false, true);
-  return result;
-}
-
-export function requestCodexControllerClose(params: Omit<Parameters<typeof requestCodexController>[0], 'command'>): CodexControllerClosed {
-  const result = requestCodexController({ ...params, command: 'close' });
-  if (result.status !== 'closed') clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller close returned the wrong result', false, true);
-  return result;
-}
-
-export function requestCodexControllerVerify(params: Readonly<{
-  controllerProof: CodexControllerLeaseProofV1;
-  channelDir?: string;
-  statusDir?: string;
-  token?: string;
-  generation?: string;
-  timeoutMs?: number;
-}>): CodexControllerVerified {
-  const result = requestCodexController({
-    ...params,
-    controllerProcess: params.controllerProof.controllerProcess,
-    command: 'verify'
-  });
-  if (result.status !== 'verified') {
-    clientError('SANDBOX_CONTROL_RESULT_INVALID', 'controller verify returned the wrong result', false, true);
-  }
-  return result;
+  return exchangeSandboxControl(request, params);
 }
 
 export function requestSandboxTaskCreate(params: Readonly<{
@@ -701,8 +469,6 @@ export function requestSandboxTaskCreate(params: Readonly<{
     version: 4, id: randomUUID(), ...auth, issuedAt,
     expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
     family: 'task-create', candidate: params.candidate,
-    controllerProcess: null,
-    controllerProof: null
   };
   return exchangeSandboxControl(request, { ...params, timeoutMs: params.timeoutMs ?? 120_000 });
 }