@fitlab-ai/agent-infra 0.11.11 → 0.11.13

package/lib/agent-clients/adapters/codex.ts

@@ -4,6 +4,45 @@ import {
   codexBeforeContainerCreateHook,
   codexRecoveryChecks
 } from './codex-sandbox.ts';
+import { parseCodexLifecycleBinding } from './codex-lifecycle/binding.ts';
+import { isCodexDelegationReceiptEvidence, isCodexLifecycleActivationEvidence } from './codex-lifecycle/evidence.ts';
+import { codexControllerOperation } from './codex-lifecycle/controller-operation.ts';
+
+function codexCarrierError(code: string): Error {
+  const error = new Error(code);
+  error.name = code;
+  return error;
+}
+
+function codexStageToken(stage: string): string {
+  const tokens: Readonly<Record<string, string>> = {
+    analysis: 'a',
+    plan: 'p',
+    code: 'c',
+    'review-analysis': 'ra',
+    'review-plan': 'rp',
+    'review-code': 'rc',
+    commit: 'm'
+  };
+  const token = tokens[stage];
+  if (!token) throw codexCarrierError('CODEX_LIFECYCLE_SPAWN_IDENTITY_INVALID');
+  return token;
+}
+
+function codexLaunchCarrier(
+  adapterContext: string,
+  identity: Readonly<{ stage: string; round: number; role: string }>
+): Readonly<Record<string, string>> {
+  if (!Number.isSafeInteger(identity.round) || identity.round < 1
+    || !['executor', 'reviewer'].includes(identity.role)) {
+    throw codexCarrierError('CODEX_LIFECYCLE_SPAWN_IDENTITY_INVALID');
+  }
+  const label = `${codexStageToken(identity.stage)}_${identity.role === 'reviewer' ? 'r' : 'e'}_r${identity.round}`;
+  const taskName = `${label}${adapterContext}`;
+  const parsed = parseCodexLifecycleBinding(taskName);
+  if (!parsed) throw codexCarrierError('CODEX_LIFECYCLE_LAUNCH_CONTEXT_INVALID');
+  return Object.freeze({ task_name: parsed.taskName });
+}
 
 const codexAdapter = defineAgentClientAdapter({
   id: 'codex',
@@ -29,8 +68,11 @@ const codexAdapter = defineAgentClientAdapter({
     actualReasoningEffort: 'app-server'
   },
   orchestrationAdapter: {
+    validateActivationEvidence: isCodexLifecycleActivationEvidence,
+    validateReceiptEvidence: isCodexDelegationReceiptEvidence,
+    createLaunchCarrier: codexLaunchCarrier,
     prepareDelegation: async (...args) => {
-      const { prepareCodexOrchestrationDelegation } = await import('../../task/codex-orchestration.ts');
+      const { prepareCodexOrchestrationDelegation } = await import('./codex-orchestration.ts');
       return prepareCodexOrchestrationDelegation(...args);
     },
     recoverStarted: async (...args) => {
@@ -38,6 +80,7 @@ const codexAdapter = defineAgentClientAdapter({
       return recoverStartedLifecycleFromAdapter(...args);
     }
   },
+  sandboxControlOperation: codexControllerOperation,
   project: {
     ownedPathPrefixes: ['.codex/'],
     managed: ['.codex/hooks.json', '.codex/agents/'],

package/lib/agent-clients/adapters/index.ts

@@ -1,4 +1,3 @@
-import { AGENT_CLIENT_IDS } from '../types.ts';
 import type { AgentClientAdapter } from '../adapter.ts';
 import { claudeCodeAdapter } from './claude-code.ts';
 import { codexAdapter } from './codex.ts';
@@ -6,24 +5,12 @@ import { antigravityCliAdapter } from './antigravity-cli.ts';
 import { opencodeAdapter } from './opencode.ts';
 import { traecliAdapter } from './traecli.ts';
 
-const adaptersById = new Map(
-  [
-    claudeCodeAdapter,
-    codexAdapter,
-    antigravityCliAdapter,
-    opencodeAdapter,
-    traecliAdapter
-  ].map((adapter) => [adapter.id, adapter])
-);
-
-const BUILTIN_AGENT_CLIENT_ADAPTERS: readonly AgentClientAdapter[] = Object.freeze(
-  AGENT_CLIENT_IDS.map((id) => {
-    const adapter = adaptersById.get(id);
-    if (!adapter) {
-      throw new Error(`Missing built-in Agent Client adapter '${id}'`);
-    }
-    return adapter;
-  })
-);
+const BUILTIN_AGENT_CLIENT_ADAPTERS: readonly AgentClientAdapter[] = Object.freeze([
+  claudeCodeAdapter,
+  codexAdapter,
+  antigravityCliAdapter,
+  opencodeAdapter,
+  traecliAdapter
+]);
 
 export { BUILTIN_AGENT_CLIENT_ADAPTERS };

package/lib/agent-clients/tokens.ts

@@ -1,8 +1,9 @@
 // Active AI collaborator short tokens — the write-side whitelist for the
 // activity log. Migrated from lib/task/commands/log.ts so that the write-side
 // internal commands and the rendering side share one definition.
-export const KNOWN_AI_AGENTS: ReadonlySet<string> =
-  new Set(['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'traecli']);
+export const AGENT_TOKEN_VALUES = ['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'traecli'] as const;
+export type AgentToken = (typeof AGENT_TOKEN_VALUES)[number];
+export const KNOWN_AI_AGENTS: ReadonlySet<string> = new Set(AGENT_TOKEN_VALUES);
 
 // Long name -> short name mapping: `claude-code` reuses the existing
 // orchestration precedent, and `antigravity-cli` is the active client.
@@ -12,7 +13,7 @@ export const AGENT_LONG_NAMES: Readonly<Record<string, string>> = {
 };
 
 export const AGENT_USAGE_HINT =
-  "agent must be a short token (claude/codex/antigravity/opencode/cursor/traecli), " +
+  `agent must be a short token (${AGENT_TOKEN_VALUES.join('/')}), ` +
   "a long name (claude-code -> claude, antigravity-cli -> antigravity), or 'human'";
 
 // Strict write-side validation: the value must be exactly a short token, a

package/lib/internal/agent-client.ts

@@ -7,11 +7,11 @@ import {
 } from '../agent-clients/config.ts';
 import { normalizeCustomToolInvocations } from '../agent-clients/custom-tool-invocations.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
-import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
+import { getAgentClientAdapter, getAgentClientModelSelection } from '../agent-clients/registry.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection> [options]\n';
+const USAGE = 'Usage: agent-infra-internal agent-client <next-steps|model-selection|launch-carrier> [options]\n';
 
 type ParsedArgs = Readonly<{
   skillName: string;
@@ -20,6 +20,14 @@ type ParsedArgs = Readonly<{
   format: 'text' | 'json';
 }>;
 
+type LaunchCarrierArgs = Readonly<{
+  client: string;
+  adapterContext: string;
+  stage: string;
+  round: number;
+  role: string;
+}>;
+
 function failure(code: string, message: string): void {
   process.stdout.write(`${JSON.stringify({
     status: 'failed',
@@ -84,68 +92,112 @@ function parseArgs(args: string[]): ParsedArgs | null {
   };
 }
 
-function agentClient(args: string[] = []): void {
-  if (!ensureInternalHandlerRoute('agent-client', args)) return;
-  if (internalHandlerRoute('agent-client', 'model-selection', args[0] ?? '')) {
-    const values: Record<string, string> = {};
-    const seen = new Set<string>();
-    for (let index = 1; index < args.length; index += 1) {
-      const flag = args[index]!;
-      if (!['--client', '--format'].includes(flag) || seen.has(flag)) {
-        failure('AGENT_CLIENT_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
-        return;
-      }
-      const value = args[++index];
-      if (!value || value.startsWith('--')) {
-        failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
-        return;
-      }
-      seen.add(flag);
-      values[flag] = value;
+function parseLaunchCarrierArgs(args: string[]): LaunchCarrierArgs | null {
+  const allowed = new Set(['--client', '--adapter-context', '--stage', '--round', '--role', '--format']);
+  const values: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!allowed.has(flag) || seen.has(flag)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
+      return null;
     }
-    const client = values['--client'];
-    const format = values['--format'] ?? 'text';
-    if (!isAgentClientId(client) || !['text', 'json'].includes(format)) {
-      failure('AGENT_CLIENT_PAYLOAD_INVALID', 'model-selection requires a known --client and text|json format');
-      return;
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+      return null;
     }
-    const context = getAgentClientModelSelection(client);
-    if (format === 'json') {
-      process.stdout.write(`${JSON.stringify({
-        status: 'resolved', changed: false, client, context, error: null
-      })}\n`);
+    seen.add(flag);
+    values[flag] = value;
+  }
+  const round = Number(values['--round']);
+  if (!isAgentClientId(values['--client']) || !values['--adapter-context'] || !values['--stage'] || !values['--role']
+    || !Number.isSafeInteger(round) || round < 1 || (values['--format'] ?? 'json') !== 'json') {
+    failure('AGENT_CLIENT_PAYLOAD_INVALID', 'launch-carrier requires client, adapter context, stage, positive round, role, and json format');
+    return null;
+  }
+  return {
+    client: values['--client']!,
+    adapterContext: values['--adapter-context']!,
+    stage: values['--stage']!,
+    round,
+    role: values['--role']!
+  };
+}
+
+function launchCarrier(args: string[]): void {
+  const parsed = parseLaunchCarrierArgs(args);
+  if (!parsed) return;
+  const createCarrier = getAgentClientAdapter(parsed.client).orchestrationAdapter?.createLaunchCarrier;
+  if (!createCarrier) {
+    process.stdout.write(`${JSON.stringify({
+      status: 'failed', changed: false, client: parsed.client, carrier: null,
+      error: { code: 'AGENT_CLIENT_LAUNCH_CARRIER_UNSUPPORTED', message: `Agent Client '${parsed.client}' does not support lifecycle launch carriers` }
+    })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  try {
+    const carrier = createCarrier(parsed.adapterContext, { stage: parsed.stage, round: parsed.round, role: parsed.role });
+    process.stdout.write(`${JSON.stringify({ status: 'ready', changed: false, client: parsed.client, carrier, error: null })}\n`);
+  } catch (error) {
+    process.stdout.write(`${JSON.stringify({
+      status: 'failed', changed: false, client: parsed.client, carrier: null,
+      error: { code: error instanceof Error && error.name ? error.name : 'AGENT_CLIENT_LAUNCH_CARRIER_INVALID', message: error instanceof Error ? error.message : String(error) }
+    })}\n`);
+    process.exitCode = 1;
+  }
+}
+
+function modelSelection(args: string[]): void {
+  const values: Record<string, string> = {};
+  const seen = new Set<string>();
+  for (let index = 1; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!['--client', '--format'].includes(flag) || seen.has(flag)) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `invalid or duplicate option '${flag}'`);
       return;
     }
-    if (context.kind === 'interactive-only') {
-      process.stdout.write(`Model selection: interactive-only\nCommand: ${context.command}\n${context.guidance}\n`);
-    } else {
-      process.stdout.write(`Model selection: ${context.completeness} catalog\nSource: ${context.source}\n`);
-      for (const model of context.models) {
-        const efforts = model.reasoningEfforts?.length
-          ? ` (${model.reasoningEfforts.join(', ')})`
-          : '';
-        process.stdout.write(`- ${model.id}${efforts}\n`);
-      }
-      if (context.guidance) process.stdout.write(`${context.guidance}\n`);
+    const value = args[++index];
+    if (!value || value.startsWith('--')) {
+      failure('AGENT_CLIENT_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+      return;
     }
+    seen.add(flag);
+    values[flag] = value;
+  }
+  const client = values['--client'];
+  const format = values['--format'] ?? 'text';
+  if (!isAgentClientId(client) || !['text', 'json'].includes(format)) {
+    failure('AGENT_CLIENT_PAYLOAD_INVALID', 'model-selection requires a known --client and text|json format');
     return;
   }
-  const parsed = parseArgs(args);
-  if (!parsed || process.exitCode) return;
+  const context = getAgentClientModelSelection(client);
+  if (format === 'json') {
+    process.stdout.write(`${JSON.stringify({ status: 'resolved', changed: false, client, context, error: null })}\n`);
+    return;
+  }
+  renderModelSelection(context);
+}
 
-  let config: Record<string, unknown>;
-  try {
-    const configPath = path.join(process.cwd(), '.agents', '.airc.json');
-    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as unknown;
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-      throw new Error('configuration root must be an object');
-    }
-    config = raw as Record<string, unknown>;
-  } catch (error) {
-    failure('AGENT_CLIENT_CONFIG_INVALID', String(error));
+function renderModelSelection(context: ReturnType<typeof getAgentClientModelSelection>): void {
+  if (context.kind === 'interactive-only') {
+    process.stdout.write(`Model selection: interactive-only\nCommand: ${context.command}\n${context.guidance}\n`);
     return;
   }
+  process.stdout.write(`Model selection: ${context.completeness} catalog\nSource: ${context.source}\n`);
+  for (const model of context.models) {
+    const efforts = model.reasoningEfforts?.length ? ` (${model.reasoningEfforts.join(', ')})` : '';
+    process.stdout.write(`- ${model.id}${efforts}\n`);
+  }
+  if (context.guidance) process.stdout.write(`${context.guidance}\n`);
+}
 
+function renderNextSteps(args: string[]): void {
+  const parsed = parseArgs(args);
+  if (!parsed || process.exitCode) return;
+  const config = readAgentClientConfig();
+  if (!config) return;
   try {
     const clients = normalizeAgentClients(config);
     const custom = normalizeCustomToolInvocations(config);
@@ -157,32 +209,49 @@ function agentClient(args: string[] = []): void {
       ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
       ...(parsed.version ? { version: parsed.version } : {})
     });
-    if (parsed.format === 'json') {
-      process.stdout.write(`${JSON.stringify({
-        status: 'rendered',
-        changed: false,
-        commands,
-        diagnostics: custom.diagnostics,
-        error: null
-      })}\n`);
-      return;
-    }
-    for (const command of commands) {
-      process.stdout.write(`  - ${command.displayName}: ${command.command}\n`);
-    }
-    for (const diagnostic of custom.diagnostics) {
-      process.stderr.write(`${diagnostic.code} at ${diagnostic.path}\n`);
-    }
+    writeNextStepOutput(parsed.format, commands, custom.diagnostics);
   } catch (error) {
     if (error instanceof AgentClientConfigError) {
       failure(error.code, error.message);
       return;
     }
-    failure(
-      'AGENT_CLIENT_RENDER_INVALID',
-      error instanceof Error ? error.message : String(error)
-    );
+    failure('AGENT_CLIENT_RENDER_INVALID', error instanceof Error ? error.message : String(error));
+  }
+}
+
+function readAgentClientConfig(): Record<string, unknown> | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(process.cwd(), '.agents', '.airc.json'), 'utf8')) as unknown;
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) throw new Error('configuration root must be an object');
+    return raw as Record<string, unknown>;
+  } catch (error) {
+    failure('AGENT_CLIENT_CONFIG_INVALID', String(error));
+    return null;
+  }
+}
+
+function writeNextStepOutput(
+  format: ParsedArgs['format'],
+  commands: ReturnType<typeof renderNextStepCommands>,
+  diagnostics: ReturnType<typeof normalizeCustomToolInvocations>['diagnostics']
+): void {
+  if (format === 'json') {
+    process.stdout.write(`${JSON.stringify({ status: 'rendered', changed: false, commands, diagnostics, error: null })}\n`);
+    return;
+  }
+  for (const command of commands) process.stdout.write(`  - ${command.displayName}: ${command.command}\n`);
+  for (const diagnostic of diagnostics) process.stderr.write(`${diagnostic.code} at ${diagnostic.path}\n`);
+}
+
+function agentClient(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('agent-client', args)) return;
+  if (internalHandlerRoute('agent-client', 'launch-carrier', args[0] ?? '')) {
+    return launchCarrier(args);
+  }
+  if (internalHandlerRoute('agent-client', 'model-selection', args[0] ?? '')) {
+    return modelSelection(args);
   }
+  renderNextSteps(args);
 }
 
 export { agentClient };

package/lib/internal/cli-route-inventory.ts

@@ -36,8 +36,8 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-create': ['input'],
   'task-qualification': ['proposal', 'confirm', 'supersede', 'revoke'],
   'sandbox-control': ['serve', 'execute', 'recover', 'client'],
-  'agent-client': ['next-steps', 'model-selection'],
-  'codex-lifecycle': ['preflight', 'capability-arm', 'hook-event', 'resolve-start', 'resolve-stop', 'consume'],
+  'agent-client': ['next-steps', 'model-selection', 'launch-carrier'],
+  'codex-lifecycle': ['preflight', 'hook-event', 'resolve-start', 'resolve-stop', 'consume'],
   'codex-sandbox-controller': ['verify-context', 'run'],
   'git-workflow': ['inspect', 'preview-tree', 'snapshot', 'compare-trees', 'commit', 'push-rebased'],
   'task-delivery': ['deliver'],

package/lib/internal/sandbox-control.ts

@@ -1,33 +1,12 @@
 import {
   recoverSandboxControl,
   requestSandboxControl,
-  requestSandboxTaskFinalization,
   SandboxControlClientError
 } from '../sandbox/control/client.ts';
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.ts';
-import { serializeTaskFinalizationEnvelope, type TaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
-
-type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
-
-function writeFinalizationEnvelope(
-  status: FinalizationStatus,
-  accepted: boolean,
-  error: { code: string; message: string; retryable: boolean },
-  changed: boolean | null = false,
-  result: unknown = null,
-  requestId: string | null = null
-): void {
-  process.stdout.write(serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error }));
-}
-
-function finalizationErrorStatus(error: { retryable: boolean; code: string }): FinalizationStatus {
-  if (error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') return 'unknown';
-  return error.retryable ? 'blocked' : 'failed';
-}
 
 function writeClientError(error: SandboxControlClientError): void {
   process.stderr.write(`${error.detail.message}\n`);
@@ -45,78 +24,6 @@ function recoveredExitCode(response: Awaited<ReturnType<typeof recoverSandboxCon
   return response.exitCode ?? 1;
 }
 
-function finalizationResponseOutput(response: Awaited<ReturnType<typeof requestSandboxTaskFinalization>>): string {
-  try {
-    const value = JSON.parse(response.stdout) as Partial<TaskFinalizationEnvelope>;
-    if (value.version === 2
-      && value.status
-      && ['completed', 'failed', 'blocked', 'unknown'].includes(value.status)
-      && (typeof value.changed === 'boolean' || value.changed === null)) {
-      return serializeTaskFinalizationEnvelope({
-        status: value.status,
-        changed: value.changed,
-        accepted: true,
-        requestId: response.id,
-        result: value.result ?? null,
-        error: value.error ?? null
-      });
-    }
-  } catch {
-    // Preserve non-envelope output for diagnostics from the executor.
-  }
-  return response.stdout;
-}
-
-function sandboxFinalizationClient(args: string[]): void {
-  if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
-    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
-    writeFinalizationEnvelope('failed', false, error);
-    process.stderr.write('Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n');
-    process.exitCode = 1;
-    return;
-  }
-  const agent = normalizeAgentToken(args[3]);
-  if (!agent) {
-    const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: `invalid --agent: ${AGENT_USAGE_HINT}`, retryable: false };
-    writeFinalizationEnvelope('failed', false, error);
-    process.exitCode = 1;
-    return;
-  }
-  let response;
-  try {
-    response = requestSandboxTaskFinalization({ agent });
-  } catch (error) {
-    if (!(error instanceof SandboxControlClientError)) throw error;
-    const status = finalizationErrorStatus(error.detail);
-    writeFinalizationEnvelope(status, error.accepted, error.detail, status === 'unknown' ? null : false, null, error.requestId);
-    writeClientError(error);
-    process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
-    return;
-  }
-  if (response.phase === 'rejected') {
-    const error = response.error ?? {
-      code: 'SANDBOX_CONTROL_REJECTED',
-      message: 'sandbox control rejected the finalization request',
-      retryable: false
-    };
-    const status = finalizationErrorStatus(error);
-    writeFinalizationEnvelope(
-      status,
-      error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN',
-      error,
-      status === 'unknown' ? null : false,
-      null,
-      response.id
-    );
-    process.stderr.write(`${error.message}\n`);
-    process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
-    return;
-  }
-  process.stdout.write(finalizationResponseOutput(response));
-  process.stderr.write(response.stderr);
-  process.exitCode = response.exitCode ?? 1;
-}
-
 async function sandboxControl(args: string[]): Promise<void> {
   if (!ensureInternalHandlerRoute('sandbox-control', args)) return;
   const [operation, ...rest] = args;
@@ -165,10 +72,6 @@ async function sandboxControl(args: string[]): Promise<void> {
   }
   if (internalHandlerRoute('sandbox-control', 'client', operation ?? '')) {
     const [family = '', ...commandArgs] = rest;
-    if (family === 'task-finalization') {
-      sandboxFinalizationClient(commandArgs);
-      return;
-    }
     let response;
     try {
       response = requestSandboxControl({ family, args: commandArgs });

package/lib/internal/task-finalization.ts

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import {
   createDirectHostExecutionContext,
   dispatchTaskControlOperation,
@@ -6,8 +7,10 @@ import {
 import { applyTaskFinalization } from '../task/finalization.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import { resolveSandboxControlTransport } from './task-operation-registry.ts';
-import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.ts';
+import { quiesceSandboxControlForTaskCompletion } from '../sandbox/control/lifecycle.ts';
+import { resolveTaskRuntimeRoot } from '../task/runtime-paths.ts';
 import { serializeTaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
+import { verifyTaskEvent } from '../task/verification.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
@@ -79,25 +82,34 @@ async function taskFinalization(args: string[] = []): Promise<void> {
   };
   const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
   if (transport.kind === 'sandbox-local') {
-    try {
-      const response = requestSandboxTaskFinalization({ agent: boundOperation.request.agent });
-      process.stdout.write(response.stdout);
-      process.stderr.write(response.stderr);
-      process.exitCode = response.exitCode ?? 1;
-      return;
-    } catch (error) {
-      const clientError = error instanceof SandboxControlClientError ? error : null;
-      const detail = clientError
-        ? clientError.detail
-        : { code: 'SANDBOX_CONTROL_CLIENT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
-      const status = detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
-        ? 'unknown'
-        : detail.retryable ? 'blocked' : 'failed';
-      const changed = status === 'unknown' ? null : false;
-      process.stdout.write(envelope(status, changed, clientError?.accepted ?? false, null, detail, clientError?.requestId ?? null));
-      process.exitCode = exitCode(status);
+    const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
+    const taskId = process.env.AGENT_INFRA_TASK_ID;
+    const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+    const controlRootId = process.env.AGENT_INFRA_CONTROL_ROOT_ID;
+    if (!statusDir || !taskId || !generation || !controlRootId || taskId !== resolved.taskId) {
+      const detail = { code: 'TASK_CONTROL_TRANSPORT_INVALID', message: 'sandbox task control identity is incomplete', retryable: false };
+      process.stdout.write(envelope('failed', false, true, null, detail));
+      process.exitCode = 1;
       return;
     }
+    const result = await applyTaskFinalization(boundOperation.request, {
+      repoRoot,
+      beforeLifecycle: async (currentTaskId) => {
+        if (currentTaskId !== taskId) throw new Error('SANDBOX_CONTROL_IDENTITY_MISMATCH');
+        await quiesceSandboxControlForTaskCompletion(
+          path.join(resolveTaskRuntimeRoot(taskId, { repoRoot }), 'sandbox-control'),
+          { taskId, generation, controlRootId, statusDir }
+        );
+      },
+      preflight: (request, options) => verifyTaskEvent(
+        { ...request, event: 'complete-task.hard-preflight' }, options
+      )
+    });
+    const status = result.status === 'prepared' ? 'failed' : result.status;
+    process.stdout.write(envelope(status, result.changed, true, result, result.error
+      ?? (result.status === 'prepared' ? { code: 'TASK_FINALIZATION_PREPARATION_INCOMPLETE', message: 'finalization did not commit', retryable: true } : null)));
+    process.exitCode = exitCode(status);
+    return;
   }
   const result = await dispatchTaskControlOperation(
     createDirectHostExecutionContext({ repoRoot }),

package/lib/internal/task-lifecycle.ts

@@ -10,7 +10,7 @@ import type { TaskLifecycleResult } from '../task/lifecycle.ts';
 import type { AgentClientLifecycleRecoveryResult as LifecycleRecoveryResult } from '../agent-clients/adapter.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --auto\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.filter((intent) => intent !== 'complete').join(', ')}\nrecover-started: --auto\n`;
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);

package/lib/internal/task-operation-registry.ts

@@ -54,8 +54,8 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'sandbox-control', 'client', 'conditional', 'progress', 'delegated'),
     descriptor('internal', 'agent-client', 'next-steps', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'agent-client', 'model-selection', 'non-task', 'diagnostic', 'none'),
+    descriptor('internal', 'agent-client', 'launch-carrier', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'codex-lifecycle', 'preflight', 'non-task', 'diagnostic', 'none'),
-    descriptor('internal', 'codex-lifecycle', 'capability-arm', 'conditional', 'progress'),
     descriptor('internal', 'codex-lifecycle', 'hook-event', 'conditional', 'progress'),
     descriptor('internal', 'codex-lifecycle', 'resolve-start', 'conditional', 'progress'),
     descriptor('internal', 'codex-lifecycle', 'resolve-stop', 'conditional', 'progress'),

package/lib/internal/task-validate.ts

@@ -155,7 +155,7 @@ function inplaceValidation(config: ReturnType<typeof loadConfig>, target: Return
   const row = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, target.branch));
   if (!row) throw new Error('SANDBOX_VALIDATION_CONTAINER_NOT_FOUND');
   const control = sandboxControlPaths({
-    base: config.controlBase, project: config.project,
+    base: config.controlBase, repoRoot: config.repoRoot, project: config.project,
     container: row.name, identity: target.workspace
   });
   const manifest = readSandboxControlManifest(control.manifestPath);