@fitlab-ai/agent-infra 0.9.4 → 0.9.6

package/lib/sandbox/control/lifecycle.ts

@@ -0,0 +1,342 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { buildProcessTreeStopCommand } from '../../server/process-control.ts';
+import { processIdentityMatches } from '../../server/process-state.ts';
+import type {
+  SandboxControlExecution,
+  SandboxControlManifest,
+  SandboxControlStatus
+} from './protocol.ts';
+import {
+  parseSandboxControlStatus,
+  readExecution,
+  terminateSandboxControlExecution
+} from './state.ts';
+
+type OwnerIdentity = Readonly<{ pid: number; startTime: string }>;
+type BrokerOwner = OwnerIdentity & Readonly<{ version: 2; token: string; generation: string }>;
+
+const DEFAULT_QUIESCE_TIMEOUT_MS = 7_000;
+const QUIESCING_FILE = 'quiescing.json';
+const BROKER_STARTING_FILE = 'broker-starting.json';
+
+function regularFile(filePath: string): boolean {
+  try {
+    const stat = fs.lstatSync(filePath);
+    return stat.isFile() && !stat.isSymbolicLink();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+export function isSandboxControlRootQuiescing(root: string): boolean {
+  return fs.existsSync(path.join(path.resolve(root), QUIESCING_FILE));
+}
+
+function markSandboxControlRootQuiescing(root: string): void {
+  const markerPath = path.join(root, QUIESCING_FILE);
+  try {
+    fs.writeFileSync(markerPath, `${JSON.stringify({ version: 1, startedAt: Date.now() })}\n`, {
+      mode: 0o600,
+      flag: 'wx'
+    });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+    if (!regularFile(markerPath)) throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+  }
+}
+
+function readStartupOwner(filePath: string): { raw: string; owner: OwnerIdentity } | null {
+  if (!fs.existsSync(filePath)) return null;
+  if (!regularFile(filePath)) throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+  const raw = fs.readFileSync(filePath, 'utf8');
+  try {
+    const record = JSON.parse(raw) as Partial<OwnerIdentity> & { version?: unknown };
+    if (record.version !== 1 || !Number.isSafeInteger(record.pid) || (record.pid ?? 0) <= 0
+      || typeof record.startTime !== 'string') return null;
+    return { raw, owner: { pid: record.pid!, startTime: record.startTime } };
+  } catch {
+    return null;
+  }
+}
+
+async function waitForStartupTransition(root: string, timeoutMs: number): Promise<void> {
+  const transitionPath = path.join(root, BROKER_STARTING_FILE);
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const transition = readStartupOwner(transitionPath);
+    if (!fs.existsSync(transitionPath)) return;
+    if (transition && !ownerLive(transition.owner)) {
+      try {
+        if (fs.readFileSync(transitionPath, 'utf8') === transition.raw) fs.unlinkSync(transitionPath);
+      } catch {
+        // A concurrent startup transition changed or removed the record.
+      }
+      continue;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+}
+
+export async function acquireSandboxControlBrokerStartup(
+  root: string,
+  owner: OwnerIdentity,
+  timeoutMs = 5_000
+): Promise<() => void> {
+  const resolvedRoot = path.resolve(root);
+  const transitionPath = path.join(resolvedRoot, BROKER_STARTING_FILE);
+  const record = `${JSON.stringify({ version: 1, ...owner })}\n`;
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (isSandboxControlRootQuiescing(resolvedRoot)) throw new Error('SANDBOX_CONTROL_QUIESCING');
+    try {
+      fs.writeFileSync(transitionPath, record, { mode: 0o600, flag: 'wx' });
+      if (isSandboxControlRootQuiescing(resolvedRoot)) {
+        try {
+          if (fs.readFileSync(transitionPath, 'utf8') === record) fs.unlinkSync(transitionPath);
+        } catch {
+          // The deletion side owns the transition now.
+        }
+        throw new Error('SANDBOX_CONTROL_QUIESCING');
+      }
+      return () => {
+        try {
+          if (fs.readFileSync(transitionPath, 'utf8') === record) fs.unlinkSync(transitionPath);
+        } catch {
+          // A newer transition or deletion owns the path.
+        }
+      };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      const transition = readStartupOwner(transitionPath);
+      if (transition && !ownerLive(transition.owner)) {
+        try {
+          if (fs.readFileSync(transitionPath, 'utf8') === transition.raw) fs.unlinkSync(transitionPath);
+        } catch {
+          // A concurrent transition changed the record.
+        }
+        continue;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 25));
+    }
+  }
+  throw new Error('SANDBOX_CONTROL_BROKER_START_TRANSITION');
+}
+
+export function readSandboxControlManifest(manifestPath: string): SandboxControlManifest {
+  if (!regularFile(manifestPath)) throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  let manifest: Partial<SandboxControlManifest>;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as Partial<SandboxControlManifest>;
+  } catch {
+    throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  }
+  if (manifest.version !== 3) {
+    throw new Error('SANDBOX_CONTROL_MANIFEST_VERSION_INVALID: expected version 3; container-only recreation is required');
+  }
+  if (typeof manifest.repoRoot !== 'string' || typeof manifest.worktreeRoot !== 'string'
+    || typeof manifest.project !== 'string' || typeof manifest.container !== 'string'
+    || typeof manifest.branch !== 'string' || !['task-bound', 'branch-only'].includes(manifest.mode ?? '')
+    || (manifest.taskId !== null && typeof manifest.taskId !== 'string')
+    || typeof manifest.channelDir !== 'string' || typeof manifest.publicStatusDir !== 'string'
+    || typeof manifest.processingDir !== 'string' || typeof manifest.token !== 'string'
+    || typeof manifest.generation !== 'string') throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  const root = path.dirname(path.resolve(manifestPath));
+  if (path.resolve(manifest.channelDir) !== path.join(root, 'channel')
+    || path.resolve(manifest.publicStatusDir) !== path.join(root, 'public')
+    || path.resolve(manifest.processingDir) !== path.join(root, 'processing')) {
+    throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+  }
+  return manifest as SandboxControlManifest;
+}
+
+function readBrokerOwner(filePath: string): BrokerOwner | null {
+  if (!fs.existsSync(filePath)) return null;
+  if (!regularFile(filePath)) throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  let owner: Partial<BrokerOwner> | null;
+  try {
+    owner = JSON.parse(fs.readFileSync(filePath, 'utf8')) as Partial<BrokerOwner> | null;
+  } catch {
+    throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  }
+  if (!owner || owner.version !== 2 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
+    || typeof owner.startTime !== 'string' || typeof owner.token !== 'string'
+    || typeof owner.generation !== 'string') throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  return owner as BrokerOwner;
+}
+
+function readStatusOwner(filePath: string): SandboxControlStatus | null {
+  if (!fs.existsSync(filePath)) return null;
+  if (!regularFile(filePath)) throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  try {
+    return parseSandboxControlStatus(JSON.parse(fs.readFileSync(filePath, 'utf8')));
+  } catch {
+    throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  }
+}
+
+function sameOwner(left: OwnerIdentity, right: OwnerIdentity): boolean {
+  return left.pid === right.pid && left.startTime === right.startTime;
+}
+
+function ownerLive(owner: OwnerIdentity): boolean {
+  return processIdentityMatches({ version: 1, pid: owner.pid, startTime: owner.startTime });
+}
+
+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');
+  const executions: SandboxControlExecution[] = [];
+  for (const entry of fs.readdirSync(manifest.processingDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+    const descriptor = path.join(manifest.processingDir, entry.name, 'execution.json');
+    if (!fs.existsSync(descriptor)) continue;
+    let execution: SandboxControlExecution;
+    try {
+      execution = readExecution(descriptor);
+    } catch {
+      throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+    }
+    if (execution.generation !== manifest.generation || execution.requestId !== entry.name) {
+      throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+    }
+    if (execution.child.pid <= 0 || (execution.child.processGroupId !== null
+      && (!Number.isSafeInteger(execution.child.processGroupId) || execution.child.processGroupId <= 0))) {
+      throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${entry.name}`);
+    }
+    executions.push(execution);
+  }
+  return executions;
+}
+
+function processGroupAlive(groupId: number): boolean {
+  try {
+    const rows = execFileSync('ps', ['-axo', 'pgid=,stat='], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    return rows.split('\n').some((row) => {
+      const match = row.trim().match(/^(\d+)\s+(\S+)/);
+      return Number(match?.[1]) === groupId && !match?.[2]?.startsWith('Z');
+    });
+  } catch {
+    try {
+      process.kill(-groupId, 0);
+      return true;
+    } catch (error) {
+      return (error as NodeJS.ErrnoException).code === 'EPERM';
+    }
+  }
+}
+
+function executionAlive(execution: SandboxControlExecution, platform: NodeJS.Platform): boolean {
+  if (platform !== 'win32' && execution.child.processGroupId) {
+    return processGroupAlive(execution.child.processGroupId);
+  }
+  return processIdentityMatches({ version: 1, pid: execution.child.pid, startTime: execution.child.startTime });
+}
+
+async function waitForExit(owner: OwnerIdentity, timeoutMs: number): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!ownerLive(owner)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 25));
+  }
+  return !ownerLive(owner);
+}
+
+function signalOwner(owner: OwnerIdentity, platform: NodeJS.Platform, force: boolean): void {
+  try {
+    if (platform === 'win32') {
+      const command = buildProcessTreeStopCommand(owner.pid, platform);
+      if (command.kind === 'exec') execFileSync(command.command, command.args, { stdio: 'ignore' });
+      return;
+    }
+    process.kill(owner.pid, force ? 'SIGKILL' : 'SIGTERM');
+  } catch {
+    // The identity checks decide whether the owner actually exited.
+  }
+}
+
+function mergeExecutions(...groups: readonly SandboxControlExecution[][]): SandboxControlExecution[] {
+  const merged = new Map<string, SandboxControlExecution>();
+  for (const execution of groups.flat()) merged.set(`${execution.requestId}:${execution.nonce}`, execution);
+  return [...merged.values()];
+}
+
+export async function quiesceSandboxControlRoot(
+  root: string,
+  options: { platform?: NodeJS.Platform; timeoutMs?: number } = {}
+): Promise<'missing' | 'stale' | 'stopped'> {
+  const resolvedRoot = path.resolve(root);
+  if (!fs.existsSync(resolvedRoot)) return 'missing';
+  const rootStat = fs.lstatSync(resolvedRoot);
+  if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+
+  for (const directory of [path.join(resolvedRoot, 'public'), path.join(resolvedRoot, 'processing')]) {
+    if (!fs.existsSync(directory)) continue;
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('SANDBOX_CONTROL_CHANNEL_INVALID');
+  }
+
+  markSandboxControlRootQuiescing(resolvedRoot);
+  await waitForStartupTransition(resolvedRoot, options.timeoutMs ?? DEFAULT_QUIESCE_TIMEOUT_MS);
+
+  const manifestPath = path.join(resolvedRoot, 'manifest.json');
+  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 ? { version: 1 as const, ...status.broker } : null;
+  const brokerLive = broker ? ownerLive(broker) : false;
+  const statusLive = statusOwner ? ownerLive(statusOwner) : false;
+
+  if (manifest && broker && (broker.token !== manifest.token || broker.generation !== manifest.generation)) {
+    throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  }
+  if (manifest && status && status.generation !== manifest.generation) {
+    throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  }
+  if (broker && statusOwner && !sameOwner(broker, statusOwner) && (brokerLive || statusLive)) {
+    throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+  }
+  if (!manifest && brokerLive) throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
+
+  const platform = options.platform ?? process.platform;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_QUIESCE_TIMEOUT_MS;
+  let executions = manifest ? readExecutions(manifest) : [];
+  const owner: OwnerIdentity | null = brokerLive ? broker : statusLive ? statusOwner : null;
+  if (!owner) {
+    if (manifest && !broker && !status) throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
+    for (const execution of executions) {
+      if (!terminateSandboxControlExecution(execution, { platform, timeoutMs })) {
+        throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+      }
+    }
+    if (executions.some((execution) => executionAlive(execution, platform))) {
+      throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+    }
+    return broker || status ? 'stale' : 'missing';
+  }
+
+  signalOwner(owner, platform, false);
+  if (await waitForExit(owner, timeoutMs)) {
+    if (executions.some((execution) => executionAlive(execution, platform))) {
+      throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+    }
+    return 'stopped';
+  }
+
+  if (manifest) executions = mergeExecutions(executions, readExecutions(manifest));
+  for (const execution of executions) {
+    if (!terminateSandboxControlExecution(execution, { platform, timeoutMs })) {
+      throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
+    }
+  }
+  signalOwner(owner, platform, true);
+  if (!await waitForExit(owner, timeoutMs)) throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
+  if (executions.some((execution) => executionAlive(execution, platform))) {
+    throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
+  }
+  return 'stopped';
+}

package/lib/sandbox/control/protocol.ts

@@ -1,35 +1,62 @@
+import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../../task/create.ts';
+
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
-export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration'] as const;
+export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
+export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
+export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
+export const SANDBOX_CONTROL_FUTURE_SKEW_MS = 1_000;
+export const SANDBOX_CONTROL_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'] as const;
 
 export type SandboxControlFamily = typeof SANDBOX_CONTROL_FAMILIES[number];
-
 export type SandboxControlManifest = Readonly<{
-  version: 1;
-  repoRoot: string;
-  project: string;
-  container: string;
-  branch: string;
-  mode: 'task-bound' | 'branch-only';
-  taskId: string | null;
-  token: string;
-  channelDir: string;
+  version: 3; repoRoot: string; worktreeRoot: string; project: string; container: string;
+  branch: string; mode: 'task-bound' | 'branch-only'; taskId: string | null; token: string;
+  generation: string; channelDir: string; publicStatusDir: string; processingDir: string;
 }>;
-
-export type SandboxControlRequest = Readonly<{
-  version: 1;
-  id: string;
-  token: string;
-  family: SandboxControlFamily;
-  args: string[];
+type RequestBase = Readonly<{
+  version: 2; id: string; token: string; generation: string; issuedAt: number; expiresAt: number;
 }>;
-
+export type SandboxTaskCommandRequest = RequestBase & Readonly<{
+  family: 'task-lifecycle' | 'task-orchestration'; args: string[];
+}>;
+export type SandboxTaskCreateRequest = RequestBase & Readonly<{
+  family: 'task-create'; candidate: TaskCreateCandidateV1;
+}>;
+export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskCreateRequest;
+export type SandboxControlError = Readonly<{ code: string; message: string; retryable: boolean }>;
 export type SandboxControlResponse = Readonly<{
-  version: 1;
-  id: string;
-  exitCode: number;
-  stdout: string;
-  stderr: string;
+  version: 2; id: string; phase: 'accepted' | 'completed' | 'rejected'; exitCode: number | null;
+  stdout: string; stderr: string; error: SandboxControlError | null;
 }>;
+export type SandboxControlStatus = Readonly<{
+  version: 1; generation: string; broker: { pid: number; startTime: string };
+  state: 'starting' | 'healthy' | 'busy' | 'parked'; reasonCode: string | null;
+  activeRequestId: string | null; updatedAt: number;
+}>;
+export type SandboxControlLease = Readonly<{
+  version: 1; generation: string; nonce: string; owner: { pid: number; startTime: string };
+  issuedAt: number; expiresAt: number; taskId: string | null; branch: string; reason: string;
+}>;
+export type SandboxControlExecution = Readonly<{
+  version: 1; generation: string; requestId: string; nonce: string;
+  child: { pid: number; startTime: string; processGroupId: number | null };
+  phase: 'prepared' | 'running' | 'terminating'; updatedAt: number;
+}>;
+
+export class SandboxControlProtocolError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+  constructor(code: string, message: string, retryable = false) {
+    super(`${code}: ${message}`);
+    this.name = 'SandboxControlProtocolError';
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+function fail(code: string, message: string, retryable = false): never {
+  throw new SandboxControlProtocolError(code, message, retryable);
+}
 
 export function isSandboxControlFamily(value: string): value is SandboxControlFamily {
   return SANDBOX_CONTROL_FAMILIES.includes(value as SandboxControlFamily);
@@ -37,39 +64,74 @@ export function isSandboxControlFamily(value: string): value is SandboxControlFa
 
 export function validateSandboxControlRequest(
   value: unknown,
-  manifest: SandboxControlManifest
+  manifest: SandboxControlManifest,
+  options: { now?: number } = {}
 ): SandboxControlRequest {
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
-    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request must be an object');
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request must be an object');
   }
-  const request = value as Partial<SandboxControlRequest>;
+  const request = value as Record<string, unknown>;
   if (
-    request.version !== 1
-    || typeof request.id !== 'string'
-    || !/^[a-f0-9-]{16,64}$/.test(request.id)
-    || request.token !== manifest.token
-    || typeof request.family !== 'string'
-    || !isSandboxControlFamily(request.family)
-    || !Array.isArray(request.args)
-    || !request.args.every((arg) => typeof arg === 'string')
-  ) {
-    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+    request.version !== 2 || typeof request.id !== 'string'
+    || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
+    || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
+    || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt)
+  ) fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+  if (request.generation !== manifest.generation) {
+    fail('SANDBOX_CONTROL_GENERATION_INVALID', 'request generation does not match the broker');
   }
-  if (manifest.mode !== 'task-bound' || !manifest.taskId) {
-    throw new Error('SANDBOX_CONTROL_BRANCH_ONLY: branch-only sandboxes cannot coordinate tasks');
+  const issuedAt = request.issuedAt as number;
+  const expiresAt = request.expiresAt as number;
+  const now = options.now ?? Date.now();
+  if (expiresAt <= issuedAt || expiresAt - issuedAt > SANDBOX_CONTROL_ADMISSION_WINDOW_MS || issuedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
+    fail('SANDBOX_CONTROL_REQUEST_DEADLINE_INVALID', 'request admission deadline is invalid');
   }
+  if (now > expiresAt) fail('SANDBOX_CONTROL_REQUEST_EXPIRED', 'request admission deadline has passed', true);
   if (Buffer.byteLength(JSON.stringify(request), 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
-    throw new Error('SANDBOX_CONTROL_REQUEST_TOO_LARGE: request exceeds the control limit');
+    fail('SANDBOX_CONTROL_REQUEST_TOO_LARGE', 'request exceeds the control limit');
+  }
+  if (request.family === 'task-create') {
+    const expected = ['candidate', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+    if (Object.keys(request).sort().join(',') !== expected.sort().join(',')) {
+      fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+    }
+    return { ...request, candidate: validateTaskCreateCandidate(request.candidate) } as SandboxTaskCreateRequest;
+  }
+  const expected = ['args', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'token', 'version'];
+  if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
+    || !Array.isArray(request.args) || !request.args.every((arg) => typeof arg === 'string')) {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request schema or authorization is invalid');
+  }
+  if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+    fail(
+      'SANDBOX_CONTROL_BRANCH_ONLY',
+      "branch-only sandboxes cannot coordinate tasks; return to the host and run 'ai sandbox start --recreate <task-ref-or-correct-branch>'"
+    );
+  }
+  if (request.family === 'task-orchestration'
+    && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))) {
+    fail('SANDBOX_CONTROL_REQUEST_INVALID', 'worktree binding is reserved for the control broker');
   }
-  return request as SandboxControlRequest;
+  return request as SandboxTaskCommandRequest;
 }
 
-export function bindSandboxControlTask(
-  request: SandboxControlRequest,
-  taskId: string
-): string[] {
-  if (request.args.length === 0) {
-    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: command arguments are required');
-  }
+export function bindSandboxControlTask(request: SandboxControlRequest, taskId: string): string[] {
+  if (request.family === 'task-create') fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-create requests do not bind a current task');
+  if (request.args.length === 0) fail('SANDBOX_CONTROL_REQUEST_INVALID', 'command arguments are required');
   return [taskId, ...request.args.slice(1)];
 }
+
+export function controlError(error: unknown): SandboxControlError {
+  if (error instanceof SandboxControlProtocolError) {
+    return { code: error.code, message: error.message, retryable: error.retryable };
+  }
+  const message = error instanceof Error ? error.message : String(error);
+  const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'SANDBOX_CONTROL_INTERNAL_ERROR';
+  const retryable = new Set([
+    'SANDBOX_CONTROL_BUSY',
+    'SANDBOX_CONTROL_HANDOFF_ACTIVE',
+    'SANDBOX_CONTROL_REQUEST_EXPIRED',
+    'SANDBOX_WORKTREE_BINDING_LOST'
+  ]).has(code);
+  return { code, message, retryable };
+}