@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/lib/run/index.ts

@@ -38,54 +38,90 @@ export type RunSkillOptions = {
   writeStderr?: (chunk: string) => void;
 };
 
-const USAGE = `Usage: ai run <skill> [task-ref] [args...] [--tui <name>] [--recreate]
+const USAGE = `Usage: ai run --skill <skill> [--task <task-ref>] [--tui <name>] [--recreate] [-- <skill-args...>]
 
 Task skills are scheduled inside the sandbox tmux session; ai run returns once
 the tmux window is created. --recreate authorizes container-only replacement
 when in-place sandbox recovery fails; it is not included in the TUI prompt.
 
 Examples:
-  ai run create-task "describe the task" --tui codex
-  ai run code-task #7 --tui codex --recreate`;
+  ai run --skill create-task "describe the task" --tui codex
+  ai run --skill code-task --task 7 --tui codex --recreate`;
 
-function extractTui(args: string[]): { rest: string[]; tui: string | null } {
-  const rest: string[] = [];
+function optionValue(args: string[], index: number, option: string): string {
+  const value = args[index + 1];
+  if (!value || value.startsWith('--')) throw new Error(`${option} requires a value`);
+  return value;
+}
+
+function extractHostOptions(args: string[]): {
+  positionals: string[];
+  forwarded: string[];
+  skill: string | null;
+  taskRef: string | null;
+  tui: string | null;
+  recreate: boolean;
+} {
+  const positionals: string[] = [];
+  const forwarded: string[] = [];
+  let skill: string | null = null;
+  let taskRef: string | null = null;
   let tui: string | null = null;
+  let recreate = false;
+  let separator = false;
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i] as string;
-    if (arg === '--tui') {
-      const value = args[i + 1];
-      if (!value) throw new Error('--tui requires a value');
-      tui = value;
+    if (separator) {
+      forwarded.push(arg);
+    } else if (arg === '--') {
+      separator = true;
+    } else if (arg === '--skill') {
+      if (skill !== null) throw new Error("duplicate option '--skill'");
+      skill = optionValue(args, i, '--skill');
       i += 1;
-      continue;
+    } else if (arg === '--task') {
+      if (taskRef !== null) throw new Error("duplicate option '--task'");
+      taskRef = optionValue(args, i, '--task');
+      i += 1;
+    } else if (arg === '--tui') {
+      if (tui !== null) throw new Error("duplicate option '--tui'");
+      tui = optionValue(args, i, '--tui');
+      i += 1;
+    } else if (arg === '--recreate') {
+      if (recreate) throw new Error("duplicate option '--recreate'");
+      recreate = true;
+    } else if (arg.startsWith('-')) {
+      throw new Error(`Unknown option '${arg}'`);
+    } else {
+      positionals.push(arg);
     }
-    rest.push(arg);
   }
-  return { rest, tui };
+  return { positionals, forwarded, skill, taskRef, tui, recreate };
 }
 
 export function parseRunArgs(args: string[]): ParsedRunArgs {
   if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
     throw new Error(USAGE);
   }
-  const { rest: withRecoveryFlags, tui } = extractTui(args);
-  const recreate = withRecoveryFlags.includes('--recreate');
-  const rest = withRecoveryFlags.filter((arg) => arg !== '--recreate');
-  const [skill = '', maybeTaskRef, ...remaining] = rest;
+  const { positionals, forwarded, skill, taskRef, tui, recreate } = extractHostOptions(args);
+  if (!skill) throw new Error("option '--skill' is required");
   const spec = getSkillRunSpec(skill);
   if (!spec) throw new Error(`Unknown skill '${skill}'`);
   if (spec.kind === 'create') {
+    if (taskRef !== null) throw new Error("create-task does not accept '--task'");
     if (recreate) throw new Error('--recreate is only valid for sandbox task runs');
-    const createArgs = rest.slice(1);
+    const createArgs = [...positionals, ...forwarded];
     if (createArgs.length === 0) throw new Error('create-task requires a description');
     return { skill, taskRef: null, args: createArgs, tui };
   }
-  if (!maybeTaskRef) throw new Error(`${skill} requires a task-ref`);
+  if (positionals.length > 0) {
+    throw new Error('ai run requires --skill and --task; positional host arguments are not supported');
+  }
+  if (taskRef === null) throw new Error(`${skill} requires a task-ref`);
   return {
     skill,
-    taskRef: maybeTaskRef,
-    args: remaining,
+    taskRef,
+    args: forwarded,
     tui,
     ...(recreate ? { recreate: true as const } : {})
   };
@@ -200,8 +236,7 @@ export async function runSkill(args: string[], options: RunSkillOptions = {}): P
   const commandConfig = options.command ?? config?.command ?? {};
   assertAllowedByConfig(parsed.skill, commandConfig);
   const tui = selectTui(parsed.skill, { cliTui: parsed.tui, command: commandConfig });
-  const promptArgs = parsed.taskRef === null ? parsed.args : [parsed.taskRef, ...parsed.args];
-  const prompt = renderPrompt({ tui, skill: parsed.skill, args: promptArgs });
+  const prompt = renderPrompt({ tui, skill: parsed.skill, args: parsed.args });
   const [file, argv] = buildTuiCommand(tui, prompt);
   const command = [file, ...argv];
 

package/lib/sandbox/control/client.ts

@@ -20,7 +20,7 @@ import type {
 } from './controller-registration.ts';
 import type { ProcessIdentity } from '../../server/process-state.ts';
 import { normalizeAgentToken } from '../../agent-clients/tokens.ts';
-import { readSandboxControlStatus } from './state.ts';
+import { readSandboxControlPayload, readSandboxControlStatus } from './state.ts';
 import type { TaskCreateCandidateV1 } from '../../task/create.ts';
 
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
@@ -28,11 +28,13 @@ const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
 export class SandboxControlClientError extends Error {
   readonly detail: SandboxControlError;
   readonly accepted: boolean;
-  constructor(detail: SandboxControlError, accepted = false) {
+  readonly requestId: string | null;
+  constructor(detail: SandboxControlError, accepted = false, requestId: string | null = null) {
     super(detail.message);
     this.name = 'SandboxControlClientError';
     this.detail = detail;
     this.accepted = accepted;
+    this.requestId = requestId;
   }
 }
 
@@ -40,8 +42,14 @@ function sleep(milliseconds: number): void {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
 }
 
-function clientError(code: string, message: string, retryable: boolean, accepted = false): never {
-  throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted);
+function clientError(
+  code: string,
+  message: string,
+  retryable: boolean,
+  accepted = false,
+  requestId: string | null = null
+): never {
+  throw new SandboxControlClientError({ code, message: `${code}: ${message}`, retryable }, accepted, requestId);
 }
 
 function preflight(statusDir: string, generation: string, now = Date.now()): void {
@@ -68,13 +76,35 @@ function preflight(statusDir: string, generation: string, now = Date.now()): voi
 function parseResponse(raw: string, id: string): SandboxControlResponse {
   const response = JSON.parse(raw) as SandboxControlResponse;
   if (response.version !== 2 || response.id !== id
-    || !['accepted', 'completed', 'rejected'].includes(response.phase)
-    || (response.phase === 'completed' && !Number.isInteger(response.exitCode))) {
-    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response is invalid', false);
+    || !['completed', 'rejected'].includes(response.phase)
+    || (response.phase === 'completed' && !Number.isInteger(response.exitCode))
+    || (response.outputState !== undefined && response.outputState !== 'available' && response.outputState !== 'unavailable')
+    || (response.outputState === 'available' && !response.payload)
+    || (response.outputState === 'unavailable' && response.payload !== null && response.payload !== undefined)) {
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response is invalid', false, false, id);
   }
   return response;
 }
 
+function readPublishedResponse(raw: string, id: string, channelDir: string): SandboxControlResponse {
+  const response = parseResponse(raw, id);
+  if (response.outputState !== 'available') return response;
+  const filePath = path.join(channelDir, 'responses', `${id}.payload.json`);
+  let payload;
+  try {
+    payload = readSandboxControlPayload(filePath);
+  } catch {
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker payload is missing or invalid', false, true, id);
+  }
+  if (!response.payload || response.payload.version !== payload.version
+    || response.payload.id !== payload.id || response.payload.generation !== payload.generation
+    || response.payload.stdoutBytes !== payload.stdoutBytes || response.payload.stderrBytes !== payload.stderrBytes
+    || response.payload.stdoutSha256 !== payload.stdoutSha256 || response.payload.stderrSha256 !== payload.stderrSha256) {
+    clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker payload reference is invalid', false, true, id);
+  }
+  return { ...response, stdout: payload.stdout, stderr: payload.stderr };
+}
+
 function cancelPendingRequest(requestPath: string): boolean {
   try {
     fs.unlinkSync(requestPath);
@@ -95,13 +125,16 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
   preflight(statusDir, request.generation);
   const encoded = `${JSON.stringify(request)}\n`;
   if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
-    clientError('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit', false);
+    clientError('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit', false, false, request.id);
   }
   const requestsDir = path.join(channelDir, 'requests');
   const responsesDir = path.join(channelDir, 'responses');
   const temporary = path.join(requestsDir, `.${request.id}.tmp`);
   const requestPath = path.join(requestsDir, `${request.id}.json`);
   const responsePath = path.join(responsesDir, `${request.id}.json`);
+  if (fs.existsSync(responsePath)) {
+    clientError('SANDBOX_CONTROL_REQUEST_REPLAYED', 'request id already has a terminal response', false, false, request.id);
+  }
   fs.writeFileSync(temporary, encoded, { mode: 0o600, flag: 'wx' });
   fs.renameSync(temporary, requestPath);
   const deadline = Date.now() + (params.timeoutMs ?? 30_000);
@@ -109,6 +142,8 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
   let malformedResponseRaw: string | null = null;
   let malformedResponseObservedAt = 0;
   while (Date.now() < deadline) {
+    const acceptedPath = path.join(responsesDir, `${request.id}.accepted.json`);
+    if (fs.existsSync(acceptedPath)) accepted = true;
     if (fs.existsSync(responsePath)) {
       let raw: string;
       try {
@@ -119,7 +154,7 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       }
       let response: SandboxControlResponse;
       try {
-        response = parseResponse(raw, request.id);
+        response = readPublishedResponse(raw, request.id, channelDir);
         malformedResponseRaw = null;
       } catch (error) {
         if (!(error instanceof SyntaxError)) throw error;
@@ -128,7 +163,7 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
           malformedResponseRaw = raw;
           malformedResponseObservedAt = now;
         } else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
-          clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted);
+          clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted, request.id);
         }
         sleep(25);
         continue;
@@ -136,7 +171,6 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       if (response.phase === 'accepted') {
         accepted = true;
       } else {
-        fs.rmSync(responsePath, { force: true });
         return response;
       }
     }
@@ -149,7 +183,8 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
           'SANDBOX_CONTROL_RESULT_UNKNOWN',
           'request was claimed before broker availability was lost; inspect domain state before retrying',
           false,
-          true
+          true,
+          request.id
         );
       }
     }
@@ -160,7 +195,8 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       'SANDBOX_CONTROL_RESULT_UNKNOWN',
       'accepted request did not produce a final result; inspect domain state before retrying',
       false,
-      true
+      true,
+      request.id
     );
   }
   if (!cancelPendingRequest(requestPath)) {
@@ -168,10 +204,64 @@ function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly
       'SANDBOX_CONTROL_RESULT_UNKNOWN',
       'request was claimed but no acceptance result was observed; inspect domain state before retrying',
       false,
-      true
+      true,
+      request.id
     );
   }
-  clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', `broker did not accept the request within ${params.timeoutMs ?? 30_000}ms`, true);
+  clientError('SANDBOX_CONTROL_BROKER_UNAVAILABLE', `broker did not accept the request within ${params.timeoutMs ?? 30_000}ms`, true, false, request.id);
+}
+
+export function recoverSandboxControl(requestId: string, params: Readonly<{
+  channelDir?: string;
+  timeoutMs?: number;
+}> = {}): SandboxControlResponse {
+  if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) {
+    clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'request id is invalid', false, true);
+  }
+  const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
+  const responsePath = path.join(channelDir, 'responses', `${requestId}.json`);
+  const deadline = Date.now() + (params.timeoutMs ?? 30_000);
+  let accepted = false;
+  let malformedResponseRaw: string | null = null;
+  let malformedResponseObservedAt = 0;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(path.join(channelDir, 'responses', `${requestId}.accepted.json`))) accepted = true;
+    if (fs.existsSync(responsePath)) {
+      let raw: string;
+      try {
+        raw = fs.readFileSync(responsePath, 'utf8');
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT') continue;
+        throw error;
+      }
+      let response: SandboxControlResponse;
+      try {
+        response = readPublishedResponse(raw, requestId, channelDir);
+        malformedResponseRaw = null;
+      } catch (error) {
+        if (!(error instanceof SyntaxError)) throw error;
+        const now = Date.now();
+        if (malformedResponseRaw !== raw) {
+          malformedResponseRaw = raw;
+          malformedResponseObservedAt = now;
+        } else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
+          clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted, requestId);
+        }
+        sleep(25);
+        continue;
+      }
+      if (response.phase === 'accepted') accepted = true;
+      else return response;
+    }
+    sleep(25);
+  }
+  clientError(
+    'SANDBOX_CONTROL_RESULT_UNKNOWN',
+    'request did not produce a final result; inspect domain state before retrying',
+    false,
+    accepted,
+    requestId
+  );
 }
 
 function authority(params: { token?: string; generation?: string }): { token: string; generation: string } {

package/lib/sandbox/control/executor.ts

@@ -218,7 +218,7 @@ function lifecycleFailure(code: string, message: string): SandboxControlExecutio
   };
 }
 
-function finalizationResult(result: ReturnType<typeof applyTaskFinalization>): SandboxControlExecutionResult {
+function finalizationResult(result: Awaited<ReturnType<typeof applyTaskFinalization>>): SandboxControlExecutionResult {
   const payload = {
     version: 1,
     status: result.status,
@@ -246,7 +246,7 @@ export async function executeRequest(
   options: ExecuteRequestOptions = {}
 ): Promise<SandboxControlExecutionResult> {
   if (request.family === 'task-create') {
-    const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
+    const result = await createTask(request.candidate, { repoRoot: manifest.repoRoot });
     return {
       exitCode: result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0,
       stdout: `${JSON.stringify(result)}\n`,
@@ -313,7 +313,7 @@ export async function executeRequest(
       }),
       operation
     );
-    return finalizationResult(result);
+    return finalizationResult(await result);
   }
   const boundArgs = bindSandboxControlTask(request, manifest.taskId!);
   if (request.family === 'task-orchestration') {
@@ -387,7 +387,7 @@ export async function executeRequest(
     return format(await dispatchTaskControlOperation(context, operation));
   }
   if (operation.family !== 'task-lifecycle') throw new Error('SANDBOX_CONTROL_LIFECYCLE_OPERATION_INVALID');
-  return format(dispatchTaskControlOperation(context, operation));
+    return format(await dispatchTaskControlOperation(context, operation));
 }
 
 export async function runSandboxControlExecutor(requestPath: string, nonce: string): Promise<void> {

package/lib/sandbox/control/protocol.ts

@@ -1,9 +1,14 @@
+import { createHash } from 'node:crypto';
 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_MAX_LOGICAL_RECORDS = 1024;
+export const SANDBOX_CONTROL_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+export const SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES = 1024 * 1024;
+export const SANDBOX_CONTROL_RESERVATION_BYTES = SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES + 4 * 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;
@@ -63,9 +68,43 @@ export type SandboxCodexControllerRequest = RequestBase & Readonly<{
 }>;
 export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskFinalizationRequest | SandboxTaskCreateRequest | SandboxCodexControllerRequest;
 export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
+export type SandboxControlResultEvidence = Readonly<{
+  version: 1;
+  id: string;
+  generation: string;
+  exitCode: number;
+  stdoutBytes: number;
+  stderrBytes: number;
+  stdoutSha256: string;
+  stderrSha256: string;
+  captureState: 'metadata-only';
+}>;
+export type SandboxControlPayloadReference = Readonly<{
+  version: 1;
+  id: string;
+  generation: string;
+  stdoutBytes: number;
+  stderrBytes: number;
+  stdoutSha256: string;
+  stderrSha256: string;
+}>;
+export type SandboxControlPayload = SandboxControlPayloadReference & Readonly<{
+  stdout: string;
+  stderr: string;
+}>;
+export type SandboxControlReservation = Readonly<{
+  version: 1;
+  id: string;
+  generation: string;
+  logicalRecords: 1;
+  bytes: number;
+  createdAt: number;
+}>;
 export type SandboxControlResponse = Readonly<{
   version: 2; id: string; phase: 'accepted' | 'completed' | 'rejected'; exitCode: number | null;
   stdout: string; stderr: string; error: SandboxControlError | null;
+  outputState?: 'available' | 'unavailable';
+  payload?: SandboxControlPayloadReference | null;
 }>;
 export type SandboxControlStatus = Readonly<{
   version: 2; generation: string; broker: ProcessIdentity & { brokerId: string };
@@ -97,6 +136,80 @@ function fail(code: string, message: string, retryable = false): never {
   throw new SandboxControlProtocolError(code, message, retryable);
 }
 
+export function parseSandboxControlResultEvidence(value: unknown): SandboxControlResultEvidence {
+  const evidence = value as Partial<SandboxControlResultEvidence> | null;
+  const keys = evidence && typeof evidence === 'object' ? Object.keys(evidence).sort().join(',') : '';
+  if (keys !== 'captureState,exitCode,generation,id,stderrBytes,stderrSha256,stdoutBytes,stdoutSha256,version'
+    || evidence?.version !== 1
+    || typeof evidence.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(evidence.id)
+    || typeof evidence.generation !== 'string' || evidence.generation.length === 0
+    || !Number.isSafeInteger(evidence.exitCode)
+    || !Number.isSafeInteger(evidence.stdoutBytes) || (evidence.stdoutBytes as number) < 0
+    || !Number.isSafeInteger(evidence.stderrBytes) || (evidence.stderrBytes as number) < 0
+    || (evidence.stdoutBytes as number) + (evidence.stderrBytes as number) > SANDBOX_CONTROL_MAX_RESPONSE_BYTES
+    || typeof evidence.stdoutSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(evidence.stdoutSha256)
+    || typeof evidence.stderrSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(evidence.stderrSha256)
+    || evidence.captureState !== 'metadata-only') {
+    throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+  }
+  return evidence as SandboxControlResultEvidence;
+}
+
+function validPayloadReference(value: unknown, id: string, generation: string): value is SandboxControlPayloadReference {
+  const payload = value as Partial<SandboxControlPayloadReference> | null;
+  const keys = payload && typeof payload === 'object' ? Object.keys(payload).sort().join(',') : '';
+  return keys === 'generation,id,stderrBytes,stderrSha256,stdoutBytes,stdoutSha256,version'
+    && payload?.version === 1
+    && payload.id === id
+    && payload.generation === generation
+    && Number.isSafeInteger(payload.stdoutBytes) && (payload.stdoutBytes as number) >= 0
+    && Number.isSafeInteger(payload.stderrBytes) && (payload.stderrBytes as number) >= 0
+    && (payload.stdoutBytes as number) + (payload.stderrBytes as number) <= SANDBOX_CONTROL_MAX_RESPONSE_BYTES
+    && typeof payload.stdoutSha256 === 'string' && /^[a-f0-9]{64}$/u.test(payload.stdoutSha256)
+    && typeof payload.stderrSha256 === 'string' && /^[a-f0-9]{64}$/u.test(payload.stderrSha256);
+}
+
+export function parseSandboxControlPayload(value: unknown): SandboxControlPayload {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+  const payload = value as Partial<SandboxControlPayload>;
+  const reference: Partial<SandboxControlPayloadReference> = {
+    version: payload.version,
+    id: payload.id,
+    generation: payload.generation,
+    stdoutBytes: payload.stdoutBytes,
+    stderrBytes: payload.stderrBytes,
+    stdoutSha256: payload.stdoutSha256,
+    stderrSha256: payload.stderrSha256
+  };
+  const keys = Object.keys(payload).sort().join(',');
+  if (keys !== 'generation,id,stderr,stderrBytes,stderrSha256,stdout,stdoutBytes,stdoutSha256,version'
+    || !validPayloadReference(reference, reference.id as string, reference.generation as string)
+    || typeof payload.stdout !== 'string' || typeof payload.stderr !== 'string'
+    || Buffer.byteLength(payload.stdout, 'utf8') !== payload.stdoutBytes
+    || Buffer.byteLength(payload.stderr, 'utf8') !== payload.stderrBytes
+    || createHash('sha256').update(payload.stdout, 'utf8').digest('hex') !== payload.stdoutSha256
+    || createHash('sha256').update(payload.stderr, 'utf8').digest('hex') !== payload.stderrSha256) {
+    throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+  }
+  return payload as SandboxControlPayload;
+}
+
+export function parseSandboxControlReservation(value: unknown): SandboxControlReservation {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+  const reservation = value as Partial<SandboxControlReservation>;
+  const keys = Object.keys(reservation).sort().join(',');
+  if (keys !== 'bytes,createdAt,generation,id,logicalRecords,version'
+    || reservation.version !== 1
+    || typeof reservation.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(reservation.id)
+    || typeof reservation.generation !== 'string' || reservation.generation.length === 0
+    || reservation.logicalRecords !== 1
+    || !Number.isSafeInteger(reservation.bytes) || (reservation.bytes as number) < SANDBOX_CONTROL_RESERVATION_BYTES
+    || !Number.isSafeInteger(reservation.createdAt)) {
+    throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+  }
+  return reservation as SandboxControlReservation;
+}
+
 export function isSandboxControlFamily(value: string): value is SandboxControlFamily {
   return SANDBOX_CONTROL_FAMILIES.includes(value as SandboxControlFamily);
 }