@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/lib/internal/sandbox-control.ts

@@ -1,8 +1,13 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import {
   recoverSandboxControl,
   requestSandboxControl,
   requestSandboxTaskFinalization,
   requestSandboxTaskControl,
+  requestSandboxTaskWorkflow,
+  resolveVisibleActiveShortId,
   SandboxControlClientError
 } from '../sandbox/control/client.ts';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
@@ -14,6 +19,113 @@ import {
 } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.ts';
+import { createTaskWorkflowRequest } from '../sandbox/control/task-workflow.ts';
+import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.ts';
+import { routeOrchestration } from '../task/orchestration.ts';
+import { parseArtifactName } from '../task/artifact-name.ts';
+import type { LifecycleAuthorityRequestV1 } from '../task/control-authority.ts';
+
+function valueAfter(args: readonly string[], flag: string): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag) return args[index + 1];
+    if (args[index]?.startsWith(`${flag}=`)) return args[index]!.slice(flag.length + 1);
+  }
+  return undefined;
+}
+
+function withoutValue(args: readonly string[], flag: string): string[] {
+  const result: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === flag) { index += 1; continue; }
+    if (args[index]?.startsWith(`${flag}=`)) continue;
+    result.push(args[index]!);
+  }
+  return result;
+}
+
+function lifecycleIds(authorityRef: string, taskId: string): Readonly<{ operationId: string; lifecycleRequestId: string }> {
+  const digest = (label: string) => createHash('sha256')
+    .update(`${label}\0${taskId}\0${authorityRef}`, 'utf8')
+    .digest('hex');
+  return { operationId: digest('operation'), lifecycleRequestId: digest('lifecycle-request') };
+}
+
+function lifecycleAuthorityIdentity(
+  authorityRef: string,
+  taskId: string,
+  requestId: string,
+  phase: LifecycleAuthorityRequestV1['phase'],
+  family: LifecycleAuthorityRequestV1['family'],
+  artifact: string,
+  round: number
+): LifecycleAuthorityRequestV1 | undefined {
+  const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+  if (!authorityRef || !contextPath) return undefined;
+  const routed = verifyCodexSandboxControllerContextWithWarnings(contextPath, { repoRoot: process.cwd() });
+  const buildIdentity = computeLifecycleBuildIdentity(process.cwd());
+  const hookDefinitionHash = createHash('sha256')
+    .update(readFileSync(path.join(process.cwd(), '.codex', 'hooks.json')))
+    .digest('hex');
+  const ids = lifecycleIds(authorityRef, taskId);
+  return {
+    version: 1,
+    requestId,
+    operationId: ids.operationId,
+    phase,
+    taskId,
+    family,
+    artifact,
+    round,
+    lifecycleRequestId: ids.lifecycleRequestId,
+    authorityRef,
+    expectedControlGeneration: routed.context.controlGeneration,
+    expectedControllerInstanceDigest: routed.context.controllerInstanceDigest,
+    expectedBuildIdentityDigest: createHash('sha256').update(JSON.stringify(buildIdentity)).digest('hex'),
+    expectedHookDefinitionHash: hookDefinitionHash
+  };
+}
+
+function lifecycleAuthoritySelector(args: readonly string[]): LifecycleAuthorityRequestV1 | undefined {
+  if (!isCanonicalCodexPrepare(args)) return undefined;
+  const authorityRef = valueAfter(args, '--capability-ref');
+  const taskId = args[0];
+  if (!authorityRef || !taskId) return undefined;
+  const routed = routeOrchestration(taskId);
+  if (!routed.next || !['analysis', 'plan', 'code'].includes(routed.next.stage)) return undefined;
+  return lifecycleAuthorityIdentity(
+    authorityRef,
+    taskId,
+    randomUUID(),
+    'orchestration.prepare',
+    routed.next.stage === 'analysis' ? 'analysis' : routed.next.stage === 'plan' ? 'plan' : 'code',
+    routed.next.artifact,
+    routed.next.round
+  );
+}
+
+function lifecycleWorkflowAuthoritySelector(
+  originalArgs: readonly string[],
+  workflow: ReturnType<typeof createTaskWorkflowRequest>
+): LifecycleAuthorityRequestV1 | undefined {
+  const authorityRef = valueAfter(originalArgs, '--capability-ref');
+  if (!authorityRef) return undefined;
+  if (workflow.operation === 'artifact-finalize-local') {
+    const family = valueAfter(workflow.args, '--family');
+    const artifact = valueAfter(workflow.args, '--artifact');
+    const parsed = artifact ? parseArtifactName(artifact) : null;
+    if ((family !== 'analysis' && family !== 'plan' && family !== 'code')
+      || !parsed || parsed.family !== family) return undefined;
+    return lifecycleAuthorityIdentity(authorityRef, workflow.taskId, workflow.id,
+      'artifact.finalize-local', family, artifact!, parsed.round);
+  }
+  if (workflow.operation !== 'event') return undefined;
+  const completed = /^(analysis|plan|code)\.completed$/u.exec(workflow.args[1] ?? '');
+  const artifact = valueAfter(workflow.args, '--artifact');
+  const parsed = artifact ? parseArtifactName(artifact) : null;
+  if (!completed || !parsed || parsed.family !== completed[1]) return undefined;
+  return lifecycleAuthorityIdentity(authorityRef, workflow.taskId, workflow.id,
+    'task-event.completed', completed[1] as LifecycleAuthorityRequestV1['family'], artifact!, parsed.round);
+}
 
 function isCanonicalCodexPrepare(args: readonly string[]): boolean {
   if (args[1] !== 'prepare') return false;
@@ -151,6 +263,49 @@ async function sandboxControl(args: string[]): Promise<void> {
       sandboxFinalizationClient(commandArgs);
       return;
     }
+    if (family === 'task-workflow') {
+      const command = commandArgs[0] as Parameters<typeof createTaskWorkflowRequest>[0] | undefined;
+      const taskId = process.env.AGENT_INFRA_TASK_ID;
+      const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+      if (!command || !taskId || !generation) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SANDBOX_CONTROL_REQUEST_INVALID', message: 'task-workflow requires a bound task and generation' } })}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      let workflow;
+      try {
+        const args = withoutValue(commandArgs.slice(1), '--capability-ref');
+        if (/^\d+$/.test(args[0] ?? '')) {
+          const resolved = resolveVisibleActiveShortId(args[0]!);
+          if (resolved !== taskId) throw new Error('SANDBOX_TASK_REF_MISMATCH');
+          args[0] = resolved;
+        }
+        workflow = createTaskWorkflowRequest(command, args, taskId, generation);
+      }
+      catch (error) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SANDBOX_CONTROL_REQUEST_INVALID', message: error instanceof Error ? error.message : String(error) } })}\n`);
+        process.exitCode = 1;
+        return;
+      }
+      let response;
+      try {
+        const authority = lifecycleWorkflowAuthoritySelector(commandArgs, workflow);
+        response = requestSandboxTaskWorkflow({
+          workflow,
+          ...(authority ? { authority } : {})
+        });
+      }
+      catch (error) {
+        if (!(error instanceof SandboxControlClientError)) throw error;
+        writeClientError(error);
+        process.exitCode = error.detail.retryable ? 75 : 1;
+        return;
+      }
+      process.stdout.write(response.stdout);
+      process.stderr.write(response.stderr);
+      process.exitCode = response.phase === 'rejected' ? response.error?.retryable ? 75 : 1 : response.exitCode ?? 1;
+      return;
+    }
     let response;
     try {
       if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
@@ -158,7 +313,13 @@ async function sandboxControl(args: string[]): Promise<void> {
         const proof = contextPath
           ? controllerProofFromContext(verifyCodexSandboxControllerContextWithWarnings(contextPath).context)
           : null;
-        response = requestSandboxTaskControl({ family, args: commandArgs, controllerProof: proof });
+        const authority = lifecycleAuthoritySelector(commandArgs);
+        response = requestSandboxTaskControl({
+          family,
+          args: commandArgs,
+          controllerProof: authority ? null : proof,
+          ...(authority ? { authority } : {})
+        });
       } else {
         response = requestSandboxControl({ family, args: commandArgs });
       }

package/lib/internal/task-artifact.ts

@@ -1,229 +1,26 @@
-import fs from 'node:fs';
-import path from 'node:path';
+import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.ts';
+import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-import { resolveArtifactContext } from '../task/artifact-lifecycle.ts';
-import { parseArtifactName } from '../task/artifact-lifecycle.ts';
-import { locateActivityLog, pairEntries, startedBackedRows } from '../task/activity-log.ts';
-import { finalizeLocalArtifact } from '../task/local-artifact-finalization.ts';
-import type { LocalArtifactFamily } from '../task/local-artifact-finalization.ts';
-import { resolveTaskRef } from '../task/resolve-ref.ts';
-import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
-import { getArtifactSchema } from '../task/artifact-schema.ts';
-import {
-  applyArtifactRepair,
-  initializeArtifactSkeleton,
-  inspectArtifactStructure
-} from '../task/artifact-operations.ts';
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact> [--recovery-id <id>]\n\nInspect, initialize, or finalize a workflow artifact without changing task state.\n`;
 
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> repair --family <family> --artifact <artifact> --expected-sha256 <sha256> --expected-semantic-digest <digest>\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, repair, or finalize a workflow artifact without changing task state.\n`;
-
-function failUsage(message: string): void {
-  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_PAYLOAD_INVALID', message } })}\n`);
-  process.stderr.write(USAGE);
-  process.exitCode = 2;
-}
-
-function hasOpenLocalArtifactRound(taskDir: string, family: string, round: number): boolean {
-  try {
-    const activity = locateActivityLog(fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8'));
-    if (!activity) return false;
-    const label = family === 'analysis'
-      ? 'Analyze Task'
-      : family === 'review-analysis'
-        ? 'Review Analysis'
-        : family === 'plan'
-          ? 'Plan Task'
-          : family === 'review-plan'
-            ? 'Review Plan'
-            : family === 'code'
-              ? 'Code Task'
-              : 'Review Code';
-    const qualifier = family === 'code'
-      ? '(?:, (?:fix for review-code(?:-r\\d+)?\\.md|decision II-[1-9]\\d*))?'
-      : '';
-    const expected = new RegExp(`^${label} \\(Round ${round}${qualifier}\\)$`);
-    return startedBackedRows(pairEntries(activity.entries)).some((row) => expected.test(row.step) && !row.done);
-  } catch {
-    return false;
-  }
-}
 
 function taskArtifact(args: string[] = []): void {
   if (!ensureInternalHandlerRoute('task-artifact', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (args.length < 2) { failUsage('task ref and operation are required'); return; }
-  const operation = args[1];
-  if (!internalHandlerRoute('task-artifact', 'inspect', operation ?? '')
-    && !internalHandlerRoute('task-artifact', 'init', operation ?? '')
-    && !internalHandlerRoute('task-artifact', 'repair', operation ?? '')
-    && !internalHandlerRoute('task-artifact', 'finalize-local', operation ?? '')) { failUsage(`unknown operation '${operation}'`); return; }
-  let family = '';
-  let artifact = '';
-  let locale: 'zh-CN' | 'en' | undefined;
-  let expectedSha256 = '';
-  let expectedSemanticDigest = '';
-  const seen = new Set<string>();
-  for (let index = 2; index < args.length; index += 1) {
-    const flag = args[index]!;
-    if (flag !== '--family' && flag !== '--artifact' && flag !== '--locale' && flag !== '--expected-sha256' && flag !== '--expected-semantic-digest') { failUsage(`unknown option '${flag}'`); return; }
-    if (seen.has(flag)) { failUsage(`duplicate option '${flag}'`); return; }
-    const value = args[++index];
-    if (!value || value.startsWith('--')) { failUsage(`option '${flag}' requires a value`); return; }
-    seen.add(flag);
-    if (flag === '--family') family = value;
-    else if (flag === '--artifact') artifact = value;
-    else if (flag === '--locale') {
-      if (value !== 'zh-CN' && value !== 'en') { failUsage("option '--locale' must be 'zh-CN' or 'en'"); return; }
-      locale = value;
-    } else if (flag === '--expected-sha256') expectedSha256 = value;
-    else expectedSemanticDigest = value;
-  }
-  if (!family) { failUsage("option '--family' is required"); return; }
-  if ((operation === 'init' || operation === 'repair' || operation === 'finalize-local') && !artifact) { failUsage("option '--artifact' is required"); return; }
-  if (internalHandlerRoute('task-artifact', 'inspect', operation ?? '')) {
-    if (artifact || locale || expectedSha256 || expectedSemanticDigest) { failUsage("artifact options are only valid for init, repair, or finalize-local"); return; }
-    const result = resolveArtifactContext(args[0]!, family);
-    const output = family === 'code' && result.codeMode ? {
-      ...result,
-      mode: result.codeMode.mode,
-      code_max: result.codeMode.codeMax,
-      rev_max: result.codeMode.reviewMax,
-      verdict: result.codeMode.verdict,
-      next_round: result.next?.round ?? null,
-      next_artifact: result.next?.name ?? null,
-      review_artifact: result.codeMode.reviewArtifact,
-      implementation_input: result.codeMode.implementationInput,
-      decision_id: result.codeMode.decisionId,
-      decision_evidence: result.codeMode.decisionEvidence,
-      message: result.codeMode.message
-    } : result;
-    process.stdout.write(`${JSON.stringify(output)}\n`);
-    if (result.status === 'refused') process.exitCode = 1;
-    else if (result.status === 'failed') process.exitCode = 2;
-    return;
-  }
-  if (internalHandlerRoute('task-artifact', 'init', operation ?? '')) {
-    if (expectedSha256 || expectedSemanticDigest) { failUsage("repair baseline options are only valid for repair"); return; }
-    const schema = getArtifactSchema(family);
-    const resolved = resolveTaskRef(args[0]!);
-    if (!schema) { failUsage(`init does not support artifact family '${family}'`); return; }
-    if (!resolved.ok) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    const parsed = parseArtifactName(artifact);
-    if (!parsed || parsed.family !== family) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_CONTEXT_INVALID', message: `artifact '${artifact}' does not match ${family}` } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    const context = resolveArtifactContext(args[0]!, family);
-    const isNextArtifact = context.status === 'ready' && context.next?.name === artifact;
-    const isCurrentOpenArtifact = context.status === 'ready'
-      && context.taskDir !== null
-      && hasOpenLocalArtifactRound(context.taskDir, family, parsed.round);
-    if (!isNextArtifact && !isCurrentOpenArtifact) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_CONTEXT_INVALID', message: context.error?.message ?? `artifact '${artifact}' is not the next ${family} artifact` } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    if (!context.taskId || !context.taskDir) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_CONTEXT_INVALID', message: `artifact '${artifact}' does not match ${family}` } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    try {
-      const existing = fs.lstatSync(path.join(resolved.taskDir, artifact));
-      if (existing.isSymbolicLink() || !existing.isFile()) {
-        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_TARGET_INVALID', message: 'artifact target is not a regular file' } })}\n`);
-        process.exitCode = 1;
-        return;
-      }
-      const result = initializeArtifactSkeleton({ repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskDir: resolved.taskDir, family: schema.family, artifact, ...(locale ? { locale } : {}) });
-      process.stdout.write(`${JSON.stringify({ ...result, taskId: resolved.taskId, taskDir: resolved.taskDir, family, artifact })}\n`);
-      if (result.status === 'failed') process.exitCode = 1;
-      return;
-    } catch (error) {
-      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
-        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_TARGET_INVALID', message: String(error) } })}\n`);
-        process.exitCode = 1;
-        return;
-      }
-    }
-    const result = initializeArtifactSkeleton({
-      repoRoot: resolved.repoRoot,
-      taskId: context.taskId,
-      taskDir: context.taskDir,
-      family: schema.family,
-      artifact,
-      ...(locale ? { locale } : {})
-    });
-    process.stdout.write(`${JSON.stringify({ ...result, taskId: context.taskId, taskDir: context.taskDir, family, artifact })}\n`);
-    if (result.status === 'failed') process.exitCode = 1;
-    return;
-  }
-  if (internalHandlerRoute('task-artifact', 'repair', operation ?? '')) {
-    if (locale) { failUsage("option '--locale' is only valid for init"); return; }
-    if (!/^[a-f0-9]{64}$/.test(expectedSha256) || !/^[a-f0-9]{64}$/.test(expectedSemanticDigest)) {
-      failUsage("repair requires lowercase 64-character '--expected-sha256' and '--expected-semantic-digest'");
-      return;
-    }
-    const schema = getArtifactSchema(family);
-    const resolved = resolveTaskRef(args[0]!);
-    const parsed = parseArtifactName(artifact);
-    if (!schema || !parsed || parsed.family !== family) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_REPAIR_TARGET_INVALID', message: `artifact '${artifact}' does not match ${family}` } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    if (!resolved.ok) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    let content: string;
-    try { content = fs.readFileSync(path.join(resolved.taskDir, artifact), 'utf8'); }
-    catch (error) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_REPAIR_TARGET_INVALID', message: String(error) } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    const inspection = inspectArtifactStructure(content, schema);
-    if (!inspection.repair) {
-      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, artifact, family, diagnostics: inspection.diagnostics, error: { code: 'ARTIFACT_REPAIR_UNSAFE', message: inspection.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ') || 'no deterministic structural repair is available' } })}\n`);
-      process.exitCode = 1;
-      return;
-    }
-    const result = applyArtifactRepair({
-      repoRoot: resolved.repoRoot,
-      taskId: resolved.taskId,
-      taskDir: resolved.taskDir,
-      family: schema.family,
-      artifact,
-      expectedSha256,
-      expectedSemanticDigest,
-      operation: inspection.repair
-    });
-    process.stdout.write(`${JSON.stringify({ ...result, taskId: resolved.taskId, taskDir: resolved.taskDir, family, artifact })}\n`);
-    if (result.status === 'failed') process.exitCode = 1;
-    return;
-  }
-  const resolved = resolveTaskRef(args[0]!);
-  const repositoryRoot = resolved.ok ? resolved.repoRoot : process.cwd();
-  if (!artifact) { failUsage("option '--artifact' is required"); return; }
-  if (family !== 'analysis' && family !== 'plan' && family !== 'code') {
-    failUsage("finalize-local only supports 'analysis', 'plan', and 'code'");
+  let command;
+  try { command = parseArtifactCommand(args); }
+  catch (error) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: {
+      code: 'ARTIFACT_PAYLOAD_INVALID', message: error instanceof Error ? error.message : String(error)
+    } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 2;
     return;
   }
-  const result = finalizeLocalArtifact({
-    taskRef: args[0]!,
-    family: family as LocalArtifactFamily,
-    artifact,
-    repoRoot: repositoryRoot
-  });
+  const result = executeArtifactCommand(command);
   process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  if (result.status === 'refused') process.exitCode = 1;
+  else if (result.status === 'failed') process.exitCode = command.operation === 'inspect' ? 2 : 1;
 }
 
 export { taskArtifact };

package/lib/internal/task-create.ts

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
+import { resolveSandboxControlTransport } from './task-operation-registry.ts';
 import path from 'node:path';
 
 import {
-  classifySandboxControlEnvironment,
   requestSandboxTaskCreate,
   SandboxControlClientError
 } from '../sandbox/control/client.ts';
@@ -83,12 +83,12 @@ async function taskCreate(args: string[]): Promise<void> {
     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')));
-    const environment = classifySandboxControlEnvironment();
-    if (environment.kind === 'invalid') {
-      output(failed(environment.code ?? 'TASK_CONTROL_TRANSPORT_INVALID', environment.message ?? 'sandbox client control configuration is invalid'));
+    const environment = resolveSandboxControlTransport();
+    if (environment.kind === 'fail-closed') {
+      output(failed(environment.reasonCode ?? 'TASK_CONTROL_TRANSPORT_INVALID', 'sandbox client control configuration is invalid'));
       return;
     }
-    if (environment.kind === 'controlled') {
+    if (environment.kind === 'broker-client') {
       const response = requestSandboxTaskCreate({ candidate });
       if (response.phase === 'rejected') {
         const accepted = response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN';

package/lib/internal/task-event.ts

@@ -21,6 +21,7 @@ const FLAGS: Record<string, keyof TaskEventRequest> = {
   '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
   '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
   '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult',
+  '--transaction-id': 'transactionId', '--receipt-digest': 'receiptDigest', '--pr-head-sha': 'prHeadSha',
   '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
@@ -31,37 +32,45 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
-async function taskEvent(args: string[] = []): Promise<void> {
-  if (!ensureInternalHandlerRoute('task-event', args)) return;
-  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (args.length < 2 || !internalHandlerRoute('task-event', 'event', args[1] ? 'event' : '')) { usageFailure('task ref and event are required'); return; }
+export function parseTaskEventRequest(args: readonly string[]): TaskEventRequest {
+  if (args.length < 2) throw new Error('task ref and event are required');
   const request: TaskEventRequest = { taskRef: args[0]!, event: args[1]!, agent: '' };
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
     if (flag === '--orchestrated') {
-      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      if (seen.has(flag)) throw new Error(`duplicate option '${flag}'`);
       seen.add(flag); request.orchestrated = true; continue;
     }
     if (flag === '--dry-run') {
-      if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+      if (seen.has(flag)) throw new Error(`duplicate option '${flag}'`);
       seen.add(flag); request.dryRun = true; continue;
     }
     const key = FLAGS[flag];
-    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
-    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    if (!key) throw new Error(`unknown option '${flag}'`);
+    if (seen.has(flag)) throw new Error(`duplicate option '${flag}'`);
     const value = args[++index];
-    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    if (value === undefined || value.startsWith('--')) throw new Error(`option '${flag}' requires a value`);
     seen.add(flag);
     if (NUMERIC.has(key)) (request as Record<string, unknown>)[key] = Number(value);
     else if (key === 'verdict') request.verdict = value as Verdict;
     else (request as Record<string, unknown>)[key] = value;
   }
   const agent = normalizeAgentToken(String(request.agent ?? ''));
-  if (!agent) { usageFailure(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`); return; }
+  if (!agent) throw new Error(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`);
   request.agent = agent;
   const dryRunConflict = overrideDryRunConflict(request as unknown as Record<string, unknown>);
-  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  if (dryRunConflict) throw new Error(dryRunConflict.message);
+  return request;
+}
+
+async function taskEvent(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-event', args)) return;
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!internalHandlerRoute('task-event', 'event', args[1] ? 'event' : '')) { usageFailure('task ref and event are required'); return; }
+  let request: TaskEventRequest;
+  try { request = parseTaskEventRequest(args); }
+  catch (error) { usageFailure(error instanceof Error ? error.message : String(error)); return; }
   const resolved = resolveTaskRef(request.taskRef);
   if (!resolved.ok) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);

package/lib/internal/task-lifecycle.ts

@@ -7,9 +7,10 @@ import {
 import { lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import type { TaskLifecycleResult } from '../task/lifecycle.ts';
+import type { LifecycleRecoveryResult } from '../task/lifecycle-recovery.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(', ')}\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --stage <stage> --round <round> --artifact <artifact> --reason <reason>\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
@@ -61,9 +62,9 @@ async function taskLifecycle(args: string[] = []): Promise<void> {
   const result = await dispatchTaskControlOperation(
     createDirectHostExecutionContext({ repoRoot }),
     operation
-  ) as TaskLifecycleResult & { humanOverride?: unknown };
+  ) as (TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown };
   process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  if (result.status === 'failed' || result.status === 'owner-unknown' || result.status === 'conflict') process.exitCode = 1;
 }
 
 export { taskLifecycle };