@fitlab-ai/agent-infra 0.9.3 → 0.9.5

package/lib/sandbox/commands/list-running.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { runSafeEngine, runVerboseEngine } from '../shell.ts';
 import { resolveTaskBranch } from '../task-resolver.ts';
 import { isRemovedHashShortIdInput } from '../../task/short-id.ts';
+import { parseSandboxWorkspaceIdentity } from '../workspace-identity.ts';
 
 export type SandboxRow = {
   name: string;
@@ -11,6 +12,8 @@ export type SandboxRow = {
   branch: string;
   running: boolean;
   index: number | null;
+  workspaceMode?: 'task-bound' | 'branch-only' | 'legacy-invalid';
+  taskId?: string | null;
 };
 
 export function containerListFormat(): string {
@@ -36,19 +39,32 @@ export function parseLabels(csv: string): Record<string, string> {
   return labels;
 }
 
-export function parseSandboxRows(rawOutput: string, branchKey: string): SandboxRow[] {
+export function parseSandboxRows(
+  rawOutput: string,
+  branchKey: string,
+  workspaceKeys?: Readonly<{ mode: string; taskId: string }>
+): SandboxRow[] {
   if (!rawOutput) {
     return [];
   }
   return rawOutput.split('\n').map((line) => {
     const [name = '', status = '', labelsCsv = ''] = line.split('\t');
-    const branch = parseLabels(labelsCsv)[branchKey] ?? '';
+    const labels = parseLabels(labelsCsv);
+    const workspace = workspaceKeys
+      ? parseSandboxWorkspaceIdentity(labels, workspaceKeys)
+      : null;
     return {
       name,
       status,
-      branch,
+      branch: labels[branchKey] ?? '',
       running: status.startsWith('Up '),
-      index: null
+      index: null,
+      ...(workspace
+        ? {
+          workspaceMode: workspace.mode,
+          taskId: workspace.mode === 'task-bound' ? workspace.taskId : null
+        }
+        : {})
     };
   });
 }
@@ -76,7 +92,8 @@ export function sortAndIndexSandboxRows(rows: SandboxRow[]): {
 export function fetchSandboxRows(
   engine: string,
   label: string,
-  branchKey: string
+  branchKey: string,
+  workspaceKeys?: Readonly<{ mode: string; taskId: string }>
 ): { running: SandboxRow[]; nonRunning: SandboxRow[] } {
   const raw = runSafeEngine(engine, 'docker', [
     'ps',
@@ -86,7 +103,7 @@ export function fetchSandboxRows(
     '--format',
     containerListFormat()
   ]);
-  return sortAndIndexSandboxRows(parseSandboxRows(raw, branchKey));
+  return sortAndIndexSandboxRows(parseSandboxRows(raw, branchKey, workspaceKeys));
 }
 
 /**

package/lib/sandbox/commands/ls.ts

@@ -1,10 +1,15 @@
 import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import { loadConfig } from '../config.ts';
-import { sandboxBranchLabel, sandboxLabel } from '../constants.ts';
+import {
+  sandboxBranchLabel,
+  sandboxLabel,
+  sandboxTaskIdLabel,
+  sandboxWorkspaceModeLabel
+} from '../constants.ts';
 import { detectEngine } from '../engine.ts';
 import { formatTable } from '../../table.ts';
-import { lookupShortIdByBranch } from '../../task/short-id.ts';
+import { loadShortIdByTaskId } from '../../task/short-id.ts';
 import { fetchSandboxRows } from './list-running.ts';
 
 export { containerListFormat, parseLabels } from './list-running.ts';
@@ -22,20 +27,22 @@ to remove with "ai sandbox rm <branch>".
 Use "ai sandbox show <ref>" for a single sandbox's worktree and per-tool
 state paths.`;
 
-const CONTAINER_TABLE_HEADERS = ['#', 'SHORT', 'NAMES', 'STATUS', 'BRANCH'] as const;
+const CONTAINER_TABLE_HEADERS = ['#', 'SHORT', 'NAMES', 'STATUS', 'WORKSPACE', 'TASK', 'BRANCH'] as const;
 
 type ContainerTableRow = {
   row: string;
   shortId: string;
   name: string;
   status: string;
+  workspace: string;
+  taskId: string;
   branch: string;
 };
 
 export function formatContainerTable(rows: ContainerTableRow[], zebra = false): string[] {
   return formatTable(
     CONTAINER_TABLE_HEADERS,
-    rows.map((r) => [r.row, r.shortId, r.name, r.status, r.branch]),
+    rows.map((r) => [r.row, r.shortId, r.name, r.status, r.workspace, r.taskId, r.branch]),
     { zebra }
   );
 }
@@ -49,7 +56,12 @@ export function ls(args: string[] = []): void {
   const config = loadConfig();
   const engine = detectEngine(config);
   const label = sandboxLabel(config);
-  const { running, nonRunning } = fetchSandboxRows(engine, label, sandboxBranchLabel(config));
+  const { running, nonRunning } = fetchSandboxRows(
+    engine,
+    label,
+    sandboxBranchLabel(config),
+    { mode: sandboxWorkspaceModeLabel(config), taskId: sandboxTaskIdLabel(config) }
+  );
 
   p.intro(pc.cyan(`Sandbox status for ${config.project}`));
 
@@ -59,12 +71,16 @@ export function ls(args: string[] = []): void {
     p.log.warn('  No sandbox containers');
   } else {
     const tableRows: ContainerTableRow[] = ordered.map((container, i) => {
-      const shortId = container.branch ? lookupShortIdByBranch(container.branch, config.repoRoot) : null;
+      const shortId = container.taskId
+        ? loadShortIdByTaskId(config.repoRoot).get(container.taskId) ?? null
+        : null;
       return {
         row: String(i + 1),
         shortId: shortId ?? '-',
         name: container.name,
         status: container.status,
+        workspace: container.workspaceMode ?? 'legacy-invalid',
+        taskId: container.taskId ?? '-',
         branch: container.branch
       };
     });

package/lib/sandbox/commands/rebuild.ts

@@ -8,8 +8,8 @@ import { sandboxImageRefreshLabel } from '../constants.ts';
 import { detectEngine, ensureDocker } from '../engine.ts';
 import { runEngine, runOkEngine, runSafeEngine, runVerboseEngine } from '../shell.ts';
 import { pruneSandboxDanglingImages } from '../image-prune.ts';
-import { resolveTools } from '../tools.ts';
 import type { SandboxTool } from '../tools.ts';
+import { createSandboxCapabilityPlan } from '../agent-client-reconciler.ts';
 import {
   buildImageSignature,
   buildSandboxImageArgs,
@@ -97,8 +97,9 @@ export async function rebuild(args: string[]): Promise<void> {
   }
 
   const config = loadConfig();
-  const tools = resolveTools(config);
-  const preparedDockerfile = prepareDockerfile(config);
+  const capabilityPlan = createSandboxCapabilityPlan(config);
+  const tools = [...capabilityPlan.tools];
+  const preparedDockerfile = prepareDockerfile(config, capabilityPlan.image);
   const imageSignature = buildImageSignature(preparedDockerfile, tools);
   const quiet = values.quiet ?? false;
   const refresh = values.refresh ?? false;

package/lib/sandbox/commands/refresh.ts

@@ -1,128 +1,6 @@
-import { homedir } from 'node:os';
-import { parseArgs } from 'node:util';
-import {
-  buildLockedGuidance,
-  discoverProjects,
-  formatCredentialWarnings,
-  formatRemaining,
-  reconcileClaudeCredentials,
-  redactCommandError,
-  validateClaudeCredentialsEnvOverride
-} from '../credentials.ts';
-import { runProbe } from '../shell.ts';
+import { runClaudeCodeRefresh } from '../../agent-clients/adapters/claude-code-refresh.ts';
 
-const USAGE = 'Usage: ai sandbox refresh';
+const refresh = runClaudeCodeRefresh;
 
-type ReconcileOptions = NonNullable<Parameters<typeof reconcileClaudeCredentials>[1]>;
-
-type RefreshDeps = Partial<ReconcileOptions> & {
-  spawnFn?: typeof runProbe;
-  discoverFn?: typeof discoverProjects;
-  writeStdout?: (chunk: string) => unknown;
-  writeStderr?: (chunk: string) => unknown;
-};
-
-export function probeClaudeStatus(spawnFn: typeof runProbe = runProbe): { ok: boolean; stderr: string; error: string | null } {
-  const result = spawnFn('claude', ['/status'], {
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-    timeout: 30_000
-  });
-  return {
-    ok: result.status === 0,
-    stderr: result.stderr?.toString() ?? '',
-    error: result.error?.message ?? null
-  };
-}
-
-export async function refresh(args: string[], deps: RefreshDeps = {}): Promise<number> {
-  const {
-    spawnFn = runProbe,
-    execFn,
-    readFn,
-    existsFn,
-    writeFn,
-    writeHostFn,
-    discoverFn = discoverProjects,
-    writeStdout = (chunk: string) => process.stdout.write(chunk),
-    writeStderr = (chunk: string) => process.stderr.write(chunk)
-  } = deps;
-
-  if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
-    writeStdout(`${USAGE}\n`);
-    return 0;
-  }
-
-  const { positionals } = parseArgs({ args, allowPositionals: true, strict: true });
-  if (positionals.length > 0) {
-    throw new Error(USAGE);
-  }
-  validateClaudeCredentialsEnvOverride();
-
-  const home = homedir();
-  if (!home) {
-    throw new Error('sandbox: home directory is required');
-  }
-
-  const projects = discoverFn(home);
-  if (projects.length === 0) {
-    writeStdout('No project credentials to refresh.\n');
-    return 0;
-  }
-
-  const reconcileOptions = { execFn, readFn, existsFn, writeFn, writeHostFn, projects };
-  let result = reconcileClaudeCredentials(home, reconcileOptions);
-  if (result.status === 'STALE_ACCESS' && result.authoritative === null) {
-    writeStdout('Host credentials appear stale; probing claude /status to trigger refresh...\n');
-    const probe = probeClaudeStatus(spawnFn);
-    if (!probe.ok) {
-      writeStderr(`Probe failed: ${redactCommandError(probe.stderr || probe.error || 'unknown error')}\n`);
-      writeStderr('Run "claude /login" on the host to renew credentials.\n');
-      return 1;
-    }
-    writeStdout('Probe succeeded; re-inspecting host credentials.\n');
-    result = reconcileClaudeCredentials(home, reconcileOptions);
-  }
-
-  if (result.status === 'MISSING') {
-    writeStderr('No Claude Code credentials found on host.\n');
-    writeStderr('Run "claude /login" on the host to authenticate.\n');
-    return 1;
-  }
-
-  if (result.status === 'KEYCHAIN_LOCKED') {
-    writeStderr(`${buildLockedGuidance()}\n`);
-    return 1;
-  }
-
-  if (result.status === 'KEYCHAIN_ERROR') {
-    writeStderr(`Host keychain error: ${redactCommandError(result.detail || 'unknown error')}\n`);
-    writeStderr(`${buildLockedGuidance()}\n`);
-    return 1;
-  }
-
-  if (result.status === 'KEYCHAIN_WRITE_FAILED') {
-    writeStderr(`[host] keychain write failed: ${formatCredentialWarnings(result.warnings) || 'unknown error'}\n`);
-    return 1;
-  }
-
-  if (result.status !== 'OK') {
-    writeStderr('Host credentials still invalid after probe; run "claude /login".\n');
-    return 1;
-  }
-
-  if (result.authoritative && result.authoritative !== 'host' && result.hostWritten) {
-    writeStdout(`[host] reconciled from ${result.authoritative}\n`);
-  }
-
-  for (const project of projects) {
-    const action = result.filesWritten.includes(project) ? 'updated' : 'unchanged';
-    writeStdout(`[${project}] ${action}; expires in ${formatRemaining(result.expiresAt)}\n`);
-  }
-
-  for (const failure of result.fileErrors) {
-    writeStderr(`[${failure.project}] sync failed: ${failure.error}\n`);
-  }
-
-  return result.fileErrors.length > 0 ? 1 : 0;
-}
+export { probeClaudeStatus, runClaudeCodeRefresh } from '../../agent-clients/adapters/claude-code-refresh.ts';
+export { refresh };

package/lib/sandbox/commands/rm.ts

@@ -18,7 +18,7 @@ import { ENGINES, detectEngine, engineDisplayName, isManagedEngine, stopManagedV
 import { pruneSandboxDanglingImages } from '../image-prune.ts';
 import { removeManagedDir, removeWorktreeDir } from '../managed-fs.ts';
 import { runOk, runSafe, runSafeEngine } from '../shell.ts';
-import { resolveTaskBranch } from '../task-resolver.ts';
+import { resolveSandboxTarget } from '../workspace-identity.ts';
 import { toolConfigDirCandidates, toolProjectDirCandidates } from '../tools.ts';
 import { createSandboxCapabilityPlan } from '../agent-client-reconciler.ts';
 import type { SandboxTool } from '../tools.ts';
@@ -81,6 +81,16 @@ async function rmOne(
     for (const name of matchedContainers) {
       runSafeEngine(engine, 'docker', ['stop', name]);
       runSafeEngine(engine, 'docker', ['rm', name]);
+      for (const [base, label] of [
+        [path.join(config.workspaceViewBase, config.project), 'Workspace view'],
+        [path.join(config.controlBase, config.project), 'Control channel']
+      ] as const) {
+        const directory = path.join(base, name);
+        if (fs.existsSync(directory)) {
+          removeManagedDir(base, directory);
+          if (!options.quiet) p.log.success(`${label} removed: ${directory}`);
+        }
+      }
     }
     spinner.stop(pc.green(`Removed container(s): ${matchedContainers.join(', ')}`));
   } else {
@@ -224,6 +234,17 @@ async function rmPurge(config: SandboxConfig, tools: SandboxTool[]): Promise<voi
     }
   }
 
+  for (const [base, label] of [
+    [config.workspaceViewBase, 'workspace views'],
+    [config.controlBase, 'control channels']
+  ] as const) {
+    const projectDir = path.join(base, config.project);
+    if (fs.existsSync(projectDir)) {
+      removeManagedDir(base, projectDir);
+      p.log.success(`Removed project ${label}: ${projectDir}`);
+    }
+  }
+
   const shouldRemoveImage = await p.confirm({
     message: `Remove image ${config.imageName}?`,
     initialValue: false
@@ -369,6 +390,6 @@ export async function rm(args: string[]): Promise<void> {
     return;
   }
 
-  const branch = resolveTaskBranch(positionals[0] ?? '', config.repoRoot);
-  await rmOne(config, tools, branch);
+  const target = resolveSandboxTarget(positionals[0] ?? '', config.repoRoot);
+  await rmOne(config, tools, target.branch);
 }

package/lib/sandbox/commands/show.ts

@@ -3,9 +3,19 @@ import * as p from '@clack/prompts';
 import pc from 'picocolors';
 import type { SandboxConfig } from '../config.ts';
 import { loadConfig } from '../config.ts';
-import { assertValidBranchName, worktreeDirCandidates } from '../constants.ts';
-import { resolveBranchArg } from './list-running.ts';
+import {
+  assertValidBranchName,
+  containerNameCandidates,
+  sandboxBranchLabel,
+  sandboxLabel,
+  sandboxTaskIdLabel,
+  sandboxWorkspaceModeLabel,
+  worktreeDirCandidates
+} from '../constants.ts';
+import { fetchSandboxRows, selectSandboxContainer } from './list-running.ts';
 import { resolveTools, toolConfigDirCandidates } from '../tools.ts';
+import { detectEngine } from '../engine.ts';
+import { resolveSandboxTarget } from '../workspace-identity.ts';
 
 const USAGE = `Usage: ai sandbox show <branch | TASK-id | N>
 
@@ -51,10 +61,22 @@ export function show(args: string[] = []): void {
   }
 
   const config = loadConfig();
-  const branch = resolveBranchArg(args[0]!, { repoRoot: config.repoRoot });
+  const target = resolveSandboxTarget(args[0]!, config.repoRoot);
+  const branch = target.branch;
   assertValidBranchName(branch);
 
   const detail = collectSandboxDetail(config, branch);
+  const engine = detectEngine(config);
+  const rows = fetchSandboxRows(
+    engine,
+    sandboxLabel(config),
+    sandboxBranchLabel(config),
+    { mode: sandboxWorkspaceModeLabel(config), taskId: sandboxTaskIdLabel(config) }
+  );
+  const container = selectSandboxContainer(
+    [...rows.running, ...rows.nonRunning],
+    containerNameCandidates(config, branch)
+  );
 
   p.intro(pc.cyan(`Sandbox detail for ${config.project} · ${branch}`));
 
@@ -67,6 +89,10 @@ export function show(args: string[] = []): void {
     }
   }
 
+  p.log.step('Workspace identity');
+  process.stdout.write(`  Mode: ${container?.workspaceMode ?? 'legacy-invalid'}\n`);
+  process.stdout.write(`  Task: ${container?.taskId ?? '-'}\n`);
+
   for (const tool of detail.toolStates) {
     p.log.step(`${tool.name} state`);
     if (tool.entries.length === 0) {

package/lib/sandbox/commands/start.ts

@@ -9,9 +9,9 @@ import { detectEngine } from '../engine.ts';
 import { ensureSandboxReady } from '../recovery.ts';
 import {
   fetchSandboxRows,
-  resolveBranchArg,
   selectSandboxContainer,
 } from './list-running.ts';
+import { resolveSandboxTarget } from '../workspace-identity.ts';
 
 const USAGE = `Usage: ai sandbox start [--recreate] <branch | TASK-id | N>
 
@@ -56,7 +56,8 @@ export async function start(args: string[]): Promise<void> {
 
   const config = loadConfig();
   const engine = detectEngine(config);
-  const branch = resolveBranchArg(parsed.target, { repoRoot: config.repoRoot });
+  const target = resolveSandboxTarget(parsed.target, config.repoRoot);
+  const branch = target.branch;
   assertValidBranchName(branch);
 
   const { running, nonRunning } = fetchSandboxRows(
@@ -79,11 +80,12 @@ export async function start(args: string[]): Promise<void> {
     config,
     engine,
     branch,
+    workspace: target.workspace,
     row: found,
     allowRecreate: parsed.recreate,
-    recreate: async (targetBranch) => {
+    recreate: async () => {
       const { create } = await import('./create.ts');
-      await create([targetBranch, '--no-refresh']);
+      await create([target.requestedRef, '--no-refresh']);
     }
   });
   const message = ready.path === 'healthy'

package/lib/sandbox/config.ts

@@ -55,6 +55,8 @@ export type SandboxConfig = {
   worktreeBase: string;
   shareBase: string;
   shellConfigBase: string;
+  workspaceViewBase: string;
+  controlBase: string;
   dotfilesDir: string;
   engine: string | null;
   runtimes: string[];
@@ -188,6 +190,8 @@ export function loadConfig({
     worktreeBase: hostJoin(home, '.agent-infra', 'worktrees', project),
     shareBase: hostJoin(home, '.agent-infra', 'share', project),
     shellConfigBase: hostJoin(home, '.agent-infra', 'config', project),
+    workspaceViewBase: hostJoin(home, '.agent-infra', 'workspace-views'),
+    controlBase: hostJoin(home, '.agent-infra', 'sandbox-control'),
     dotfilesDir: hostJoin(home, '.agent-infra', 'dotfiles'),
     engine,
     runtimes,

package/lib/sandbox/constants.ts

@@ -103,6 +103,14 @@ export function sandboxBranchLabel(config: Pick<SandboxPathConfig, 'project'>):
   return `${sandboxLabel(config)}.branch`;
 }
 
+export function sandboxWorkspaceModeLabel(config: Pick<SandboxPathConfig, 'project'>): string {
+  return `${sandboxLabel(config)}.workspace-mode`;
+}
+
+export function sandboxTaskIdLabel(config: Pick<SandboxPathConfig, 'project'>): string {
+  return `${sandboxLabel(config)}.task-id`;
+}
+
 export function sandboxImageConfigLabel(config: Pick<SandboxPathConfig, 'project'>): string {
   return `${sandboxLabel(config)}.image-config`;
 }

package/lib/sandbox/control/client.ts

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import {
+  SANDBOX_CONTROL_MAX_BYTES,
+  isSandboxControlFamily,
+  type SandboxControlRequest,
+  type SandboxControlResponse,
+  type SandboxTaskCreateRequest
+} from './protocol.ts';
+import type { TaskCreateCandidateV1 } from '../../task/create.ts';
+
+function sleep(milliseconds: number): void {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+
+function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly<{
+  channelDir?: string;
+  timeoutMs?: number;
+}>): SandboxControlResponse {
+  const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
+  const encoded = `${JSON.stringify(request)}\n`;
+  if (Buffer.byteLength(encoded, 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_TOO_LARGE: request exceeds the control limit');
+  }
+  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`);
+  fs.writeFileSync(temporary, encoded, { mode: 0o600, flag: 'wx' });
+  fs.renameSync(temporary, requestPath);
+  const deadline = Date.now() + (params.timeoutMs ?? 30_000);
+  while (Date.now() < deadline) {
+    if (fs.existsSync(responsePath)) {
+      const raw = fs.readFileSync(responsePath, 'utf8');
+      fs.unlinkSync(responsePath);
+      const response = JSON.parse(raw) as SandboxControlResponse;
+      if (response.version !== 1 || response.id !== request.id || !Number.isInteger(response.exitCode)) {
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID: broker response is invalid');
+      }
+      return response;
+    }
+    sleep(25);
+  }
+  throw new Error(`SANDBOX_CONTROL_TIMEOUT: broker did not respond within ${params.timeoutMs ?? 30_000}ms`);
+}
+
+export function requestSandboxControl(params: Readonly<{
+  family: string;
+  args: string[];
+  channelDir?: string;
+  token?: string;
+  timeoutMs?: number;
+}>): SandboxControlResponse {
+  if (!isSandboxControlFamily(params.family)) {
+    throw new Error(`SANDBOX_CONTROL_COMMAND_DENIED: '${params.family}' is not allowed`);
+  }
+  if (params.family === 'task-create') throw new Error("SANDBOX_CONTROL_COMMAND_DENIED: 'task-create' requires a typed candidate");
+  const token = params.token ?? process.env.AGENT_INFRA_CONTROL_TOKEN;
+  if (!token) throw new Error('SANDBOX_CONTROL_UNAVAILABLE: control token is missing');
+  const id = randomUUID();
+  const request: SandboxControlRequest = { version: 1, id, token, family: params.family, args: params.args };
+  return exchangeSandboxControl(request, params);
+}
+
+export function requestSandboxTaskCreate(params: Readonly<{
+  candidate: TaskCreateCandidateV1;
+  channelDir?: string;
+  token?: string;
+  timeoutMs?: number;
+}>): SandboxControlResponse {
+  const token = params.token ?? process.env.AGENT_INFRA_CONTROL_TOKEN;
+  if (!token) throw new Error('SANDBOX_CONTROL_UNAVAILABLE: control token is missing');
+  const request: SandboxTaskCreateRequest = {
+    version: 1, id: randomUUID(), token, family: 'task-create', candidate: params.candidate
+  };
+  return exchangeSandboxControl(request, { ...params, timeoutMs: params.timeoutMs ?? 120_000 });
+}

package/lib/sandbox/control/protocol.ts

@@ -0,0 +1,110 @@
+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', 'task-create'] as const;
+
+export type SandboxControlFamily = typeof SANDBOX_CONTROL_FAMILIES[number];
+
+export type SandboxControlManifest = Readonly<{
+  version: 2;
+  repoRoot: string;
+  worktreeRoot: string;
+  project: string;
+  container: string;
+  branch: string;
+  mode: 'task-bound' | 'branch-only';
+  taskId: string | null;
+  token: string;
+  channelDir: string;
+}>;
+
+export type SandboxTaskCommandRequest = Readonly<{
+  version: 1;
+  id: string;
+  token: string;
+  family: 'task-lifecycle' | 'task-orchestration';
+  args: string[];
+}>;
+
+export type SandboxTaskCreateRequest = Readonly<{
+  version: 1;
+  id: string;
+  token: string;
+  family: 'task-create';
+  candidate: TaskCreateCandidateV1;
+}>;
+
+export type SandboxControlRequest = SandboxTaskCommandRequest | SandboxTaskCreateRequest;
+
+export type SandboxControlResponse = Readonly<{
+  version: 1;
+  id: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}>;
+
+export function isSandboxControlFamily(value: string): value is SandboxControlFamily {
+  return SANDBOX_CONTROL_FAMILIES.includes(value as SandboxControlFamily);
+}
+
+export function validateSandboxControlRequest(
+  value: unknown,
+  manifest: SandboxControlManifest
+): SandboxControlRequest {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request must be an object');
+  }
+  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)
+  ) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+  }
+  if (Buffer.byteLength(JSON.stringify(request), 'utf8') > SANDBOX_CONTROL_MAX_BYTES) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_TOO_LARGE: request exceeds the control limit');
+  }
+  if (request.family === 'task-create') {
+    const keys = Object.keys(request).sort().join(',');
+    if (keys !== ['candidate', 'family', 'id', 'token', 'version'].sort().join(',')) {
+      throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+    }
+    return { ...request, candidate: validateTaskCreateCandidate(request.candidate) } as SandboxTaskCreateRequest;
+  }
+  const keys = Object.keys(request).sort().join(',');
+  if (
+    keys !== ['args', 'family', 'id', 'token', 'version'].sort().join(',')
+    || !Array.isArray(request.args)
+    || !request.args.every((arg) => typeof arg === 'string')
+  ) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: request schema or authorization is invalid');
+  }
+  if (manifest.mode !== 'task-bound' || !manifest.taskId) {
+    throw new Error('SANDBOX_CONTROL_BRANCH_ONLY: branch-only sandboxes cannot coordinate tasks');
+  }
+  if (
+    request.family === 'task-orchestration'
+    && request.args.some((arg) => arg === '--git-worktree-root' || arg.startsWith('--git-worktree-root='))
+  ) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: worktree binding is reserved for the control broker');
+  }
+  return request as SandboxTaskCommandRequest;
+}
+
+export function bindSandboxControlTask(
+  request: SandboxControlRequest,
+  taskId: string
+): string[] {
+  if (request.family === 'task-create') {
+    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: task-create requests do not bind a current task');
+  }
+  if (request.args.length === 0) {
+    throw new Error('SANDBOX_CONTROL_REQUEST_INVALID: command arguments are required');
+  }
+  return [taskId, ...request.args.slice(1)];
+}