@fitlab-ai/agent-infra 0.9.4 → 0.9.5

package/lib/internal/codex-lifecycle.ts

@@ -0,0 +1,204 @@
+import { spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  preflightCodexLifecycleEvidence,
+  resolveCodexTerminal,
+  resolveCodexThread
+} from '../agent-clients/adapters/codex-lifecycle/app-server.ts';
+import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.ts';
+import type { CodexLifecycleEvent } from '../agent-clients/adapters/codex-lifecycle/evidence.ts';
+
+const USAGE = 'Usage: agent-infra-internal codex-lifecycle <hook-event|resolve-start|resolve-stop|preflight|consume> [options]\n';
+const MANAGED_AGENT = /^agent-infra-lifecycle-(executor|reviewer)$/;
+
+type Parsed = Readonly<{ operation: string; values: Readonly<Record<string, string>> }>;
+
+function output(value: unknown): void {
+  process.stdout.write(`${JSON.stringify(value)}\n`);
+}
+
+function failure(code: string, message: string): void {
+  output({ status: 'failed', changed: false, evidence: null, diagnostics: [], error: { code, message } });
+  process.exitCode = 1;
+}
+
+function parse(args: string[]): Parsed | null {
+  if (args[0] === '--help' || args[0] === '-h') {
+    process.stdout.write(USAGE);
+    return null;
+  }
+  const operation = args[0];
+  if (!operation) {
+    failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', 'operation is required');
+    return null;
+  }
+  const allowed = {
+    'hook-event': ['--event'],
+    'resolve-start': ['--child-id'],
+    'resolve-stop': ['--child-id'],
+    preflight: ['--format', '--session-id', '--turn-id', '--tool-use-id'],
+    consume: ['--child-id', '--consumer']
+  }[operation];
+  if (!allowed) {
+    failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', 'unknown operation');
+    return null;
+  }
+  const values: Record<string, string> = {};
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!allowed.includes(flag) || Object.hasOwn(values, flag)) {
+      failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
+      return null;
+    }
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failure('CODEX_LIFECYCLE_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+      return null;
+    }
+    values[flag] = value;
+  }
+  return Object.freeze({ operation, values: Object.freeze(values) });
+}
+
+function cliVersion(): string {
+  const result = spawnSync('codex', ['--version'], { encoding: 'utf8' });
+  const version = /codex-cli\s+(\d+\.\d+\.\d+)/.exec(result.stdout ?? '')?.[1];
+  if (result.status !== 0 || !version) throw new Error('Codex CLI version is unavailable');
+  return version;
+}
+
+function hookDefinitionHash(): string {
+  const file = path.join(process.cwd(), '.codex', 'hooks.json');
+  return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+}
+
+async function readStdin(): Promise<unknown> {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    input += chunk;
+    if (Buffer.byteLength(input) > 64 * 1024) throw new Error('Codex lifecycle input exceeds 64 KiB');
+  }
+  return JSON.parse(input || '{}') as unknown;
+}
+
+function recordFromPayload(phase: string, payload: unknown): CodexLifecycleEvent | null {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Codex lifecycle hook payload must be an object');
+  }
+  const value = payload as Record<string, unknown>;
+  const text = (key: string) => typeof value[key] === 'string' ? value[key] as string : '';
+  if (!MANAGED_AGENT.test(text('nativeAgent'))) return null;
+  if (phase === 'pre-tool') return {
+    type: 'hook-spawn',
+    sessionId: text('sessionId'),
+    turnId: text('turnId'),
+    toolUseId: text('toolUseId'),
+    nativeAgent: text('nativeAgent'),
+    ...(text('requestedModel') ? { requestedModel: text('requestedModel') } : {}),
+    ...(text('requestedReasoningEffort') ? { requestedReasoningEffort: text('requestedReasoningEffort') } : {}),
+    hookDefinitionHash: text('hookDefinitionHash')
+  };
+  if (phase === 'subagent-start') return {
+    type: 'hook-child',
+    sessionId: text('sessionId'),
+    turnId: text('turnId'),
+    childThreadId: text('childThreadId'),
+    nativeAgent: text('nativeAgent')
+  };
+  if (phase === 'subagent-stop') return {
+    type: 'hook-stop',
+    sessionId: text('sessionId'),
+    turnId: text('turnId'),
+    childThreadId: text('childThreadId'),
+    nativeAgent: text('nativeAgent')
+  };
+  if (phase === 'post-tool') return null;
+  throw new Error(`unknown Codex lifecycle hook phase '${phase}'`);
+}
+
+async function codexLifecycle(args: string[] = []): Promise<void> {
+  const parsed = parse(args);
+  if (!parsed || process.exitCode) return;
+  try {
+    if (parsed.operation === 'preflight') {
+      const format = parsed.values['--format'] ?? 'json';
+      if (!['text', 'json'].includes(format)) throw new Error("format must be 'text' or 'json'");
+      const runtimeFields = [
+        parsed.values['--session-id'],
+        parsed.values['--turn-id'],
+        parsed.values['--tool-use-id']
+      ];
+      if (runtimeFields.some(Boolean) && !runtimeFields.every(Boolean)) {
+        throw new Error('preflight runtime identity requires --session-id, --turn-id, and --tool-use-id together');
+      }
+      const runtimeIdentity = runtimeFields.every(Boolean) ? {
+        sessionId: runtimeFields[0]!,
+        turnId: runtimeFields[1]!,
+        toolUseId: runtimeFields[2]!
+      } : undefined;
+      const result = await preflightCodexLifecycleEvidence(process.cwd(), runtimeIdentity);
+      if (format === 'text') {
+        process.stdout.write(`Codex lifecycle static preflight: ready\nCLI: ${result.cliVersion}\nRuntime hook liveness: ${result.runtimeLiveness ? 'observed' : 'not-yet-observed'}\n`);
+      } else output({ status: 'ready', changed: false, evidence: result, diagnostics: result.diagnostics, error: null });
+      return;
+    }
+
+    const store = createCodexLifecycleStore({ cliVersion: cliVersion() });
+    if (parsed.operation === 'hook-event') {
+      const phase = parsed.values['--event'];
+      if (!phase || !['pre-tool', 'subagent-start', 'post-tool', 'subagent-stop'].includes(phase)) {
+        throw new Error('hook-event requires a known --event');
+      }
+      const event = recordFromPayload(phase, await readStdin());
+      if (!event) {
+        output({ status: 'ignored', changed: false, evidence: null, diagnostics: [], error: null });
+        return;
+      }
+      const result = store.apply(event);
+      output({ status: result.state.status, changed: true, evidence: result.state, diagnostics: [], error: result.state.error });
+      if (result.state.status === 'invalid') process.exitCode = 1;
+      return;
+    }
+
+    const childThreadId = parsed.values['--child-id'];
+    if (!childThreadId) throw new Error(`operation '${parsed.operation}' requires --child-id`);
+    if (parsed.operation === 'resolve-start') {
+      if (store.read(childThreadId).state.spawn?.hookDefinitionHash !== hookDefinitionHash()) {
+        throw new Error('Codex lifecycle hook definition hash is stale');
+      }
+      const resolved = await resolveCodexThread(childThreadId);
+      let latest = store.apply(resolved.resolution.thread);
+      for (const reroute of resolved.reroutes) latest = store.apply(reroute);
+      latest = store.apply(resolved.resolution.settings);
+      output({ status: latest.state.status, changed: true, evidence: latest.state.startEvidence, diagnostics: resolved.diagnostics, error: latest.state.error });
+      if (latest.state.status !== 'start-ready') process.exitCode = 1;
+      return;
+    }
+    if (parsed.operation === 'resolve-stop') {
+      const terminal = await resolveCodexTerminal(childThreadId);
+      const latest = store.apply(terminal);
+      if (latest.state.status !== 'stop-ready') {
+        throw new Error(`Codex lifecycle stop evidence is not ready (status=${latest.state.status})`);
+      }
+      output({ status: latest.state.status, changed: true, evidence: latest.state.stopEvidence, diagnostics: [], error: latest.state.error });
+      return;
+    }
+    if (parsed.operation === 'consume') {
+      const consumer = parsed.values['--consumer'];
+      if (!consumer) throw new Error('consume requires --consumer');
+      const consumed = store.consume(childThreadId, consumer, hookDefinitionHash());
+      output({ status: 'consumed', changed: true, evidence: {
+        start: consumed.state.startEvidence,
+        stop: consumed.state.stopEvidence
+      }, diagnostics: [], error: null });
+    }
+  } catch (error) {
+    failure('CODEX_LIFECYCLE_FAILED', error instanceof Error ? error.message : String(error));
+  }
+}
+
+export { codexLifecycle };

package/lib/internal/task-create.ts

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { requestSandboxTaskCreate } from '../sandbox/control/client.ts';
+import { SANDBOX_CONTROL_MAX_BYTES } from '../sandbox/control/protocol.ts';
+import { validateTaskCreateCandidate } from '../task/create.ts';
+import { createTask, type TaskCreateResult } from '../task/create-service.ts';
+
+function failed(code: string, message: string): TaskCreateResult {
+  return {
+    status: 'failed', changed: false, task: { id: null, shortId: null }, issue: null,
+    operations: [], warnings: [], error: { code, message, retryable: false }
+  };
+}
+
+function output(result: TaskCreateResult): void {
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
+}
+
+function taskCreate(args: string[]): void {
+  const inputIndex = args.indexOf('--input');
+  const input = inputIndex >= 0 ? args[inputIndex + 1] : undefined;
+  if (!input || args.length !== 2 || inputIndex !== 0) {
+    output(failed('TASK_CREATE_PAYLOAD_INVALID', 'Usage: agent-infra-internal task-create --input <candidate.json>'));
+    return;
+  }
+  try {
+    const inputPath = path.resolve(input);
+    const stat = fs.lstatSync(inputPath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('TASK_CREATE_INPUT_INVALID: input must be a regular file');
+    if (stat.size > SANDBOX_CONTROL_MAX_BYTES) throw new Error('TASK_CREATE_INPUT_TOO_LARGE: input exceeds the control limit');
+    const candidate = validateTaskCreateCandidate(JSON.parse(fs.readFileSync(inputPath, 'utf8')));
+    if (process.env.AGENT_INFRA_CONTROL_TOKEN) {
+      const response = requestSandboxTaskCreate({ candidate });
+      process.stdout.write(response.stdout);
+      process.stderr.write(response.stderr);
+      process.exitCode = response.exitCode;
+      return;
+    }
+    output(createTask(candidate, { repoRoot: process.cwd() }));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'TASK_CREATE_INPUT_INVALID';
+    output(failed(code, message));
+  }
+}
+
+export { taskCreate };

package/lib/internal/task-orchestration.ts

@@ -14,13 +14,15 @@ import {
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
   sealOrchestrationDelegation,
+  startCommitAttempt,
   statusCommitIntent,
-  statusOrchestration
+  statusOrchestration,
+  terminateCommitAttempt
 } from '../task/orchestration.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|hook-stop|advance|pause|status|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-status> [options]\n';
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|hook-start|hook-stop|advance|pause|status|commit-start|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-terminate|commit-status> [options]\n';
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -43,7 +45,7 @@ function taskOrchestration(args: string[] = []): void {
   const [taskRef, intent] = args;
   if (![
     'begin-or-resume', 'route', 'prepare', 'hook-start', 'hook-stop', 'advance', 'pause', 'status',
-    'commit-begin', 'commit-checkpoint', 'commit-complete', 'commit-recover', 'commit-abort', 'commit-status'
+    'commit-start', 'commit-begin', 'commit-checkpoint', 'commit-complete', 'commit-recover', 'commit-abort', 'commit-terminate', 'commit-status'
   ].includes(intent!)) {
     usageFailure(`unknown intent '${intent}'`);
     return;
@@ -67,6 +69,7 @@ function taskOrchestration(args: string[] = []): void {
       '--model-fallback-reason', '--reasoning-effort-fallback-reason',
       '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent',
       '--baseline-head', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
+      , '--attempt', '--git-worktree-root'
     ].includes(flag)) {
       usageFailure(`unknown option '${flag}'`);
       return;
@@ -84,12 +87,14 @@ function taskOrchestration(args: string[] = []): void {
     values[flag] = value;
   }
   const commitIntentFlags: Record<string, readonly string[]> = {
-    'commit-begin': ['--agent', '--baseline-head', '--orchestrated'],
-    'commit-checkpoint': ['--token', '--kind', '--head', '--remote', '--ref'],
-    'commit-complete': ['--token', '--agent'],
-    'commit-recover': ['--agent'],
-    'commit-abort': ['--token', '--expected-head'],
-    'commit-status': []
+    'commit-start': ['--agent', '--git-worktree-root'],
+    'commit-begin': ['--agent', '--baseline-head', '--attempt', '--orchestrated', '--git-worktree-root'],
+    'commit-checkpoint': ['--token', '--kind', '--head', '--remote', '--ref', '--git-worktree-root'],
+    'commit-complete': ['--token', '--agent', '--git-worktree-root'],
+    'commit-recover': ['--agent', '--git-worktree-root'],
+    'commit-abort': ['--token', '--expected-head', '--git-worktree-root'],
+    'commit-terminate': ['--attempt', '--agent', '--code', '--git-worktree-root'],
+    'commit-status': ['--git-worktree-root']
   };
   if (intent! in commitIntentFlags) {
     const allowed = commitIntentFlags[intent!]!;
@@ -97,24 +102,33 @@ function taskOrchestration(args: string[] = []): void {
     if (invalid) { usageFailure(`intent '${intent}' does not accept '${invalid}'`); return; }
   } else {
     const commitOnly = [...seen].find((flag) => [
-      '--orchestrated', '--baseline-head', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
+      '--orchestrated', '--baseline-head', '--attempt', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
     ].includes(flag));
     if (commitOnly) { usageFailure(`intent '${intent}' does not accept '${commitOnly}'`); return; }
   }
   const requireValues = (flags: string[]) => flags.find((flag) => values[flag] === undefined);
+  const coreOptions = values['--git-worktree-root'] === undefined
+    ? {}
+    : { gitWorktreeRoot: values['--git-worktree-root'] };
   if (values['--client'] !== undefined && !isAgentClientId(values['--client'])) {
     usageFailure(`unknown client '${values['--client']}'`);
     return;
   }
   let result;
-  if (intent === 'commit-begin') {
-    const missing = requireValues(['--agent', '--baseline-head']);
+  if (intent === 'commit-start') {
+    const missing = requireValues(['--agent']);
+    if (missing) { usageFailure(`intent 'commit-start' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    result = startCommitAttempt(taskRef!, { agent }, coreOptions);
+  } else if (intent === 'commit-begin') {
+    const missing = requireValues(['--agent', '--baseline-head', '--attempt']);
     if (missing) { usageFailure(`intent 'commit-begin' requires '${missing}'`); return; }
     const agent = normalizeAgentToken(values['--agent']!);
     if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
     result = beginCommitIntent(taskRef!, {
-      agent, orchestrated, baselineHead: values['--baseline-head']!
-    });
+      agent, orchestrated, baselineHead: values['--baseline-head']!, attempt: values['--attempt']!
+    }, coreOptions);
   } else if (intent === 'commit-checkpoint') {
     const missing = requireValues(['--token', '--kind', '--head']);
     if (missing) { usageFailure(`intent 'commit-checkpoint' requires '${missing}'`); return; }
@@ -130,25 +144,36 @@ function taskOrchestration(args: string[] = []): void {
     result = checkpointCommitIntent(taskRef!, {
       token: values['--token']!, kind: values['--kind'] as 'committed' | 'pushed',
       head: values['--head']!, remote: values['--remote'], ref: values['--ref']
-    });
+    }, coreOptions);
   } else if (intent === 'commit-complete') {
     const missing = requireValues(['--token', '--agent']);
     if (missing) { usageFailure(`intent 'commit-complete' requires '${missing}'`); return; }
     const agent = normalizeAgentToken(values['--agent']!);
     if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = completeCommitIntent(taskRef!, { token: values['--token']!, agent });
+    result = completeCommitIntent(taskRef!, { token: values['--token']!, agent }, coreOptions);
   } else if (intent === 'commit-recover') {
     const missing = requireValues(['--agent']);
     if (missing) { usageFailure(`intent 'commit-recover' requires '${missing}'`); return; }
     const agent = normalizeAgentToken(values['--agent']!);
     if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = recoverCommitIntent(taskRef!, { agent });
+    result = recoverCommitIntent(taskRef!, { agent }, coreOptions);
   } else if (intent === 'commit-abort') {
     const missing = requireValues(['--token', '--expected-head']);
     if (missing) { usageFailure(`intent 'commit-abort' requires '${missing}'`); return; }
-    result = abortCommitIntent(taskRef!, { token: values['--token']!, expectedHead: values['--expected-head']! });
+    result = abortCommitIntent(taskRef!, { token: values['--token']!, expectedHead: values['--expected-head']! }, coreOptions);
+  } else if (intent === 'commit-terminate') {
+    const missing = requireValues(['--attempt', '--agent', '--code']);
+    if (missing) { usageFailure(`intent 'commit-terminate' requires '${missing}'`); return; }
+    const agent = normalizeAgentToken(values['--agent']!);
+    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
+    if (!/^[A-Z][A-Z0-9_]{2,63}$/.test(values['--code']!)) {
+      usageFailure('--code must be a stable uppercase identifier'); return;
+    }
+    result = terminateCommitAttempt(taskRef!, {
+      attempt: values['--attempt']!, agent, code: values['--code']!
+    }, coreOptions);
   } else if (intent === 'commit-status') {
-    result = statusCommitIntent(taskRef!);
+    result = statusCommitIntent(taskRef!, coreOptions);
   } else if (intent === 'begin-or-resume') {
     const missing = requireValues(['--client']);
     if (missing) { usageFailure(`intent 'begin-or-resume' requires '${missing}'`); return; }
@@ -166,6 +191,7 @@ function taskOrchestration(args: string[] = []): void {
       return;
     }
     result = beginOrResumeOrchestration(taskRef!, {
+      ...coreOptions,
       maxSteps,
       client: values['--client'] as AgentClientId,
       modelPolicy: hasAnyPolicy ? {
@@ -180,9 +206,9 @@ function taskOrchestration(args: string[] = []): void {
       } : undefined
     });
   } else if (intent === 'route') {
-    result = routeOrchestration(taskRef!);
+    result = routeOrchestration(taskRef!, coreOptions);
   } else if (intent === 'status') {
-    result = statusOrchestration(taskRef!);
+    result = statusOrchestration(taskRef!, coreOptions);
   } else if (intent === 'prepare') {
     const missing = requireValues(['--client']);
     if (missing) { usageFailure(`intent 'prepare' requires '${missing}'`); return; }
@@ -190,7 +216,7 @@ function taskOrchestration(args: string[] = []): void {
       client: values['--client'] as AgentClientId,
       requestedModel: values['--requested-model'],
       requestedReasoningEffort: values['--requested-reasoning-effort']
-    });
+    }, coreOptions);
   } else if (intent === 'hook-start') {
     const missing = requireValues([
       ...(taskRef === 'auto' ? ['--client'] : []),
@@ -206,15 +232,15 @@ function taskOrchestration(args: string[] = []): void {
       reasoningEffortFallbackReason: values['--reasoning-effort-fallback-reason']
     };
     result = taskRef === 'auto'
-      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event)
-      : activateOrchestrationDelegation(taskRef!, event);
+      ? activateMatchingOrchestrationDelegation(values['--client'] as AgentClientId, event, coreOptions)
+      : activateOrchestrationDelegation(taskRef!, event, coreOptions);
   } else if (intent === 'hook-stop') {
     if (taskRef === 'auto') {
       const missing = requireValues(['--client', '--native-agent', '--child-id']);
       if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
       result = sealMatchingOrchestrationDelegation(values['--client'] as AgentClientId, {
         nativeAgent: values['--native-agent']!, childId: values['--child-id']!
-      });
+      }, coreOptions);
     } else {
       const missing = requireValues(['--child-id', '--exit-code', '--after-fingerprint']);
       if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
@@ -224,15 +250,15 @@ function taskOrchestration(args: string[] = []): void {
         childId: values['--child-id']!, exitCode,
         afterFingerprint: values['--after-fingerprint']!,
         changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
-      });
+      }, coreOptions);
     }
   } else if (intent === 'advance') {
-    result = advanceOrchestration(taskRef!);
+    result = advanceOrchestration(taskRef!, coreOptions);
   } else {
     const missing = requireValues(['--code', '--message', '--recoverable']);
     if (missing) { usageFailure(`intent 'pause' requires '${missing}'`); return; }
     if (!['true', 'false'].includes(values['--recoverable']!)) { usageFailure('--recoverable must be true or false'); return; }
-    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true');
+    result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true', coreOptions);
   }
   process.stdout.write(`${JSON.stringify(result)}\n`);
   if (result.status === 'failed') process.exitCode = 1;

package/lib/sandbox/commands/create.ts

@@ -1345,6 +1345,7 @@ export async function create(args: string[]): Promise<void> {
             const control = materializeSandboxControl({
               base: effectiveConfig.controlBase,
               repoRoot: effectiveConfig.repoRoot,
+              worktreeRoot: worktree,
               project: effectiveConfig.project,
               container,
               branch,

package/lib/sandbox/control/client.ts

@@ -5,37 +5,29 @@ import {
   SANDBOX_CONTROL_MAX_BYTES,
   isSandboxControlFamily,
   type SandboxControlRequest,
-  type SandboxControlResponse
+  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);
 }
 
-export function requestSandboxControl(params: Readonly<{
-  family: string;
-  args: string[];
+function exchangeSandboxControl(request: SandboxControlRequest, params: Readonly<{
   channelDir?: string;
-  token?: string;
   timeoutMs?: number;
 }>): SandboxControlResponse {
-  if (!isSandboxControlFamily(params.family)) {
-    throw new Error(`SANDBOX_CONTROL_COMMAND_DENIED: '${params.family}' is not allowed`);
-  }
   const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
-  const token = params.token ?? process.env.AGENT_INFRA_CONTROL_TOKEN;
-  if (!token) throw new Error('SANDBOX_CONTROL_UNAVAILABLE: control token is missing');
-  const requestsDir = path.join(channelDir, 'requests');
-  const responsesDir = path.join(channelDir, 'responses');
-  const id = randomUUID();
-  const request: SandboxControlRequest = { version: 1, id, token, family: params.family, args: params.args };
   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 temporary = path.join(requestsDir, `.${id}.tmp`);
-  const requestPath = path.join(requestsDir, `${id}.json`);
-  const responsePath = path.join(responsesDir, `${id}.json`);
+  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);
@@ -44,7 +36,7 @@ export function requestSandboxControl(params: Readonly<{
       const raw = fs.readFileSync(responsePath, 'utf8');
       fs.unlinkSync(responsePath);
       const response = JSON.parse(raw) as SandboxControlResponse;
-      if (response.version !== 1 || response.id !== id || !Number.isInteger(response.exitCode)) {
+      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;
@@ -53,3 +45,35 @@ export function requestSandboxControl(params: Readonly<{
   }
   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

@@ -1,11 +1,14 @@
+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_FAMILIES = ['task-lifecycle', 'task-orchestration', 'task-create'] as const;
 
 export type SandboxControlFamily = typeof SANDBOX_CONTROL_FAMILIES[number];
 
 export type SandboxControlManifest = Readonly<{
-  version: 1;
+  version: 2;
   repoRoot: string;
+  worktreeRoot: string;
   project: string;
   container: string;
   branch: string;
@@ -15,14 +18,24 @@ export type SandboxControlManifest = Readonly<{
   channelDir: string;
 }>;
 
-export type SandboxControlRequest = Readonly<{
+export type SandboxTaskCommandRequest = Readonly<{
   version: 1;
   id: string;
   token: string;
-  family: SandboxControlFamily;
+  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;
@@ -42,7 +55,7 @@ export function validateSandboxControlRequest(
   if (!value || typeof value !== 'object' || Array.isArray(value)) {
     throw new Error('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'
@@ -50,6 +63,22 @@ export function validateSandboxControlRequest(
     || 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')
   ) {
@@ -58,16 +87,22 @@ export function validateSandboxControlRequest(
   if (manifest.mode !== 'task-bound' || !manifest.taskId) {
     throw new Error('SANDBOX_CONTROL_BRANCH_ONLY: branch-only sandboxes cannot coordinate tasks');
   }
-  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-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 SandboxControlRequest;
+  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');
   }