@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/lib/internal/sandbox-control.ts

@@ -1,4 +1,5 @@
 import {
+  recoverSandboxControl,
   requestSandboxControl,
   requestSandboxTaskFinalization,
   requestSandboxTaskControl,
@@ -11,6 +12,8 @@ import {
   controllerProofFromContext,
   verifyCodexSandboxControllerContextWithWarnings
 } 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';
 
 function isCanonicalCodexPrepare(args: readonly string[]): boolean {
   if (args[1] !== 'prepare') return false;
@@ -39,6 +42,22 @@ function finalizationErrorStatus(error: { retryable: boolean; code: string }): F
   return error.retryable ? 'blocked' : 'failed';
 }
 
+function writeClientError(error: SandboxControlClientError): void {
+  process.stderr.write(`${error.detail.message}\n`);
+  if (error.requestId) process.stderr.write(`SANDBOX_CONTROL_REQUEST_ID: ${error.requestId}\n`);
+}
+
+function recoveredExitCode(response: Awaited<ReturnType<typeof recoverSandboxControl>>): number {
+  if (response.phase !== 'completed') return response.exitCode ?? 1;
+  try {
+    const result = parseTaskCreateResult(JSON.parse(response.stdout));
+    if (result.control?.requestId === response.id) return taskCreateExitCode(result);
+  } catch {
+    // Other control families use their own result envelopes.
+  }
+  return response.exitCode ?? 1;
+}
+
 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 };
@@ -60,7 +79,7 @@ function sandboxFinalizationClient(args: string[]): void {
   } catch (error) {
     if (!(error instanceof SandboxControlClientError)) throw error;
     writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
-    process.stderr.write(`${error.detail.message}\n`);
+    writeClientError(error);
     process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
     return;
   }
@@ -81,8 +100,9 @@ function sandboxFinalizationClient(args: string[]): void {
 }
 
 async function sandboxControl(args: string[]): Promise<void> {
+  if (!ensureInternalHandlerRoute('sandbox-control', args)) return;
   const [operation, ...rest] = args;
-  if (operation === 'serve') {
+  if (internalHandlerRoute('sandbox-control', 'serve', operation ?? '')) {
     const manifestIndex = rest.indexOf('--manifest');
     const manifest = manifestIndex >= 0 ? rest[manifestIndex + 1] : undefined;
     if (!manifest) throw new Error('sandbox-control serve requires --manifest');
@@ -98,7 +118,7 @@ async function sandboxControl(args: string[]): Promise<void> {
     }
     return;
   }
-  if (operation === 'execute') {
+  if (internalHandlerRoute('sandbox-control', 'execute', operation ?? '')) {
     const requestIndex = rest.indexOf('--request');
     const nonceIndex = rest.indexOf('--nonce');
     const request = requestIndex >= 0 ? rest[requestIndex + 1] : undefined;
@@ -107,7 +127,25 @@ async function sandboxControl(args: string[]): Promise<void> {
     await runSandboxControlExecutor(request, nonce);
     return;
   }
-  if (operation === 'client') {
+  if (internalHandlerRoute('sandbox-control', 'recover', operation ?? '')) {
+    if (rest.length !== 1 || !rest[0]) throw new Error('sandbox-control recover requires <request-id>');
+    let response;
+    try {
+      response = recoverSandboxControl(rest[0]);
+    } catch (error) {
+      if (!(error instanceof SandboxControlClientError)) throw error;
+      writeClientError(error);
+      process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : 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
+      : recoveredExitCode(response);
+    return;
+  }
+  if (internalHandlerRoute('sandbox-control', 'client', operation ?? '')) {
     const [family = '', ...commandArgs] = rest;
     if (family === 'task-finalization') {
       sandboxFinalizationClient(commandArgs);
@@ -126,7 +164,7 @@ async function sandboxControl(args: string[]): Promise<void> {
       }
     } catch (error) {
       if (!(error instanceof SandboxControlClientError)) throw error;
-      process.stderr.write(`${error.detail.message}\n`);
+      writeClientError(error);
       process.exitCode = error.detail.retryable ? 75 : 1;
       return;
     }
@@ -140,7 +178,7 @@ async function sandboxControl(args: string[]): Promise<void> {
     }
     return;
   }
-  throw new Error('Usage: agent-infra-internal sandbox-control serve --manifest <path> | execute --request <path> --nonce <nonce> | client <family> [args...]');
+  throw new Error('Usage: agent-infra-internal sandbox-control serve --manifest <path> | execute --request <path> --nonce <nonce> | client <family> [args...] | recover <request-id>');
 }
 
 export { sandboxControl };

package/lib/internal/task-activity.ts

@@ -9,6 +9,7 @@ import type {
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-activity <task-ref> pr-review-inspect
        agent-infra-internal task-activity <task-ref> pr-review-start --agent <agent> --artifact <canonical.md> --head <40hex> [--dry-run]
@@ -43,10 +44,17 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
-function taskActivity(args: string[] = []): void {
+async function taskActivity(args: string[] = []): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-activity', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const [taskRef, kind] = args;
-  if (!taskRef || taskRef.startsWith('--') || !kind || !OPERATIONS.has(kind)) {
+  if (!taskRef || taskRef.startsWith('--') || !kind || !OPERATIONS.has(kind)
+    || ![
+      internalHandlerRoute('task-activity', 'pr-review-inspect', kind),
+      internalHandlerRoute('task-activity', 'pr-review-start', kind),
+      internalHandlerRoute('task-activity', 'pr-review-complete', kind),
+      internalHandlerRoute('task-activity', 'pr-review-terminate', kind)
+    ].some(Boolean)) {
     usageFailure('task ref and a supported PR review intent are required');
     return;
   }
@@ -72,7 +80,7 @@ function taskActivity(args: string[] = []): void {
   const allowed = ALLOWED[kind]!;
   const unexpected = Object.keys(values).find((key) => !allowed.has(key));
   if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
-  if (kind === 'pr-review-inspect') {
+  if (internalHandlerRoute('task-activity', 'pr-review-inspect', kind)) {
     const result = inspectPrReviewActivity(values as PrReviewInspectIntent);
     process.stdout.write(`${JSON.stringify(result)}\n`);
     if (result.status === 'failed') process.exitCode = 1;
@@ -81,9 +89,9 @@ function taskActivity(args: string[] = []): void {
   for (const key of COMMON) {
     if (values[key] === undefined) { usageFailure(`${kind} requires '${key}'`); return; }
   }
-  const operationRequired = kind === 'pr-review-complete'
+  const operationRequired = internalHandlerRoute('task-activity', 'pr-review-complete', kind)
     ? ['verdict', 'blockers', 'major', 'minor']
-    : kind === 'pr-review-terminate' ? ['outcome', 'reason'] : [];
+    : internalHandlerRoute('task-activity', 'pr-review-terminate', kind) ? ['outcome', 'reason'] : [];
   for (const key of operationRequired) {
     if (values[key] === undefined) { usageFailure(`${kind} requires '${key}'`); return; }
   }
@@ -94,11 +102,11 @@ function taskActivity(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, () => {
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, async () => {
       let current = applyPrReviewActivityIntent(values as PrReviewActivityIntent, { lockAlreadyHeld: true });
       if (current.status !== 'failed' || !values.overrideTicket) return current;
       if (!values.overrideTarget || !values.overrideScope) { usageFailure('override ticket requires target and scope'); return current; }
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef, ticketId: String(values.overrideTicket),
         failureId: failureId('activity-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
         target: String(values.overrideTarget), scope: String(values.overrideScope)

package/lib/internal/task-artifact.ts

@@ -1,6 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
 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\nInspect one workflow artifact family and print a read-only JSON context.\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`);
@@ -8,40 +23,207 @@ function failUsage(message: string): void {
   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; }
-  if (args[1] !== 'inspect') { failUsage(`unknown operation '${args[1]}'`); 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') { failUsage(`unknown option '${flag}'`); return; }
+    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);
-    family = value;
+    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; }
-  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;
+  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'");
+    return;
+  }
+  const result = finalizeLocalArtifact({
+    taskRef: args[0]!,
+    family: family as LocalArtifactFamily,
+    artifact,
+    repoRoot: repositoryRoot
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
 }
 
 export { taskArtifact };

package/lib/internal/task-context.ts

@@ -1,5 +1,6 @@
 import { parseTaskScope } from '../task/command-options.ts';
 import { resolveTaskContext } from '../task/resolve-ref.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-context resolve [<task-ref> | --task <task-ref> | -t <task-ref>]\n`;
 
@@ -10,8 +11,9 @@ function fail(code: string, message: string, usage = false): void {
 }
 
 function taskContext(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('task-context', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
-  if (args[0] !== 'resolve') { fail('TASK_CONTEXT_PAYLOAD_INVALID', "operation 'resolve' is required", true); return; }
+  if (!internalHandlerRoute('task-context', 'resolve', args[0] ?? '')) { fail('TASK_CONTEXT_PAYLOAD_INVALID', "operation 'resolve' is required", true); return; }
   let scope;
   try {
     scope = parseTaskScope(args.slice(1));

package/lib/internal/task-create.ts

@@ -1,25 +1,77 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { requestSandboxTaskCreate, SandboxControlClientError } from '../sandbox/control/client.ts';
+import {
+  classifySandboxControlEnvironment,
+  requestSandboxTaskCreate,
+  SandboxControlClientError
+} 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';
+import {
+  createTask,
+  parseTaskCreateResult,
+  projectTaskCreateResult,
+  taskCreateExitCode,
+  taskCreateFailure,
+  type TaskCreateControl,
+  type TaskCreateResult
+} from '../task/create-service.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-function failed(code: string, message: string, retryable = false): TaskCreateResult {
-  return {
-    status: retryable ? 'blocked' : 'failed', changed: false, task: { id: null, shortId: null }, issue: null,
-    operations: [], warnings: [], error: { code, message, retryable }
-  };
+function failed(code: string, message: string, retryable = false, control?: TaskCreateControl): TaskCreateResult {
+  return taskCreateFailure({ code, message, retryable }, control);
 }
 
 function output(result: TaskCreateResult): void {
   process.stdout.write(`${JSON.stringify(result)}\n`);
-  process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
+  process.exitCode = taskCreateExitCode(result);
+}
+
+function clientErrorControl(error: SandboxControlClientError): TaskCreateControl {
+  return {
+    requestId: error.requestId,
+    accepted: error.accepted,
+    recovery: error.accepted ? 'same-request-id' : error.detail.retryable ? 'new-request-id' : 'none'
+  };
+}
+
+function parseControlledResult(response: ReturnType<typeof requestSandboxTaskCreate>): TaskCreateResult {
+  if (response.phase !== 'completed' || response.error !== null) {
+    return failed(
+      'SANDBOX_CONTROL_RESPONSE_INVALID',
+      'SANDBOX_CONTROL_RESPONSE_INVALID: completed task-create response is invalid',
+      false,
+      { requestId: response.id, accepted: true, recovery: 'same-request-id' }
+    );
+  }
+  let result: TaskCreateResult;
+  try {
+    result = parseTaskCreateResult(JSON.parse(response.stdout));
+  } catch {
+    return failed(
+      'TASK_CREATE_RESULT_INVALID',
+      'TASK_CREATE_RESULT_INVALID: task-create result payload is invalid',
+      false,
+      { requestId: response.id, accepted: true, recovery: 'same-request-id' }
+    );
+  }
+  if (!result.control || result.control.requestId !== response.id || result.control.accepted !== true) {
+    return failed(
+      'TASK_CREATE_RESULT_INVALID',
+      'TASK_CREATE_RESULT_INVALID: controlled task-create result is missing request evidence',
+      false,
+      { requestId: response.id, accepted: true, recovery: 'same-request-id' }
+    );
+  }
+  process.stderr.write(response.stderr);
+  return result;
 }
 
-function taskCreate(args: string[]): void {
-  const inputIndex = args.indexOf('--input');
+async function taskCreate(args: string[]): Promise<void> {
+  if (!ensureInternalHandlerRoute('task-create', args)) return;
+  const inputSelector = args.includes('--input') ? 'input' : '';
+  const inputIndex = internalHandlerRoute('task-create', 'input', inputSelector) ? args.indexOf('--input') : -1;
   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>'));
@@ -31,25 +83,34 @@ function taskCreate(args: string[]): 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')));
-    if (process.env.AGENT_INFRA_CONTROL_TOKEN) {
+    const environment = classifySandboxControlEnvironment();
+    if (environment.kind === 'invalid') {
+      output(failed(environment.code ?? 'TASK_CONTROL_TRANSPORT_INVALID', environment.message ?? 'sandbox client control configuration is invalid'));
+      return;
+    }
+    if (environment.kind === 'controlled') {
       const response = requestSandboxTaskCreate({ candidate });
       if (response.phase === 'rejected') {
+        const accepted = response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN';
         output(failed(
           response.error?.code ?? 'SANDBOX_CONTROL_REJECTED',
           response.error?.message ?? response.stderr,
-          response.error?.retryable ?? false
+          response.error?.retryable ?? false,
+          {
+            requestId: response.id,
+            accepted,
+            recovery: accepted ? 'same-request-id' : response.error?.retryable ? 'new-request-id' : 'none'
+          }
         ));
         return;
       }
-      process.stdout.write(response.stdout);
-      process.stderr.write(response.stderr);
-      process.exitCode = response.exitCode;
+      output(parseControlledResult(response));
       return;
     }
-    output(createTask(candidate, { repoRoot: process.cwd() }));
+    output(await createTask(candidate, { repoRoot: process.cwd() }));
   } catch (error) {
     if (error instanceof SandboxControlClientError) {
-      output(failed(error.detail.code, error.detail.message, error.detail.retryable));
+      output(failed(error.detail.code, error.detail.message, error.detail.retryable, clientErrorControl(error)));
       return;
     }
     const message = error instanceof Error ? error.message : String(error);

package/lib/internal/task-delivery.ts

@@ -2,13 +2,15 @@ import path from 'node:path';
 
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { deliverTaskBranch } from '../task/delivery.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-delivery <task-ref> deliver --agent <agent> [--remote <name>] [--base <branch>] [--dry-run] [--cwd <path>]\n`;
 
 function taskDelivery(args: string[] = []): void {
+  if (!ensureInternalHandlerRoute('task-delivery', args)) return;
   const taskRef = args[0];
   const operation = args[1];
-  if (!taskRef || operation !== 'deliver') {
+  if (!taskRef || !internalHandlerRoute('task-delivery', 'deliver', operation ?? '')) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'DELIVERY_PAYLOAD_INVALID', message: 'task ref and deliver operation are required' } })}\n`);
     process.stderr.write(USAGE);
     process.exitCode = 1;

package/lib/internal/task-event.ts

@@ -4,6 +4,7 @@ import type { TaskEventRequest, Verdict } from '../task/events.ts';
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--orchestrated] [--dry-run]
 
@@ -13,6 +14,9 @@ Events: ${eventCatalog.join(', ')}
 
 const FLAGS: Record<string, keyof TaskEventRequest> = {
   '--agent': 'agent', '--round': 'round', '--question': 'question', '--artifact': 'artifact',
+  '--artifact-sha256': 'artifactSha256', '--semantic-digest': 'semanticDigest',
+  '--initiator': 'initiator', '--request-id': 'requestId', '--reason-code': 'reasonCode',
+  '--source-finding': 'sourceFinding', '--source-artifact': 'sourceArtifact', '--source-sha256': 'sourceSha256',
   '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
   '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
   '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
@@ -27,9 +31,10 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
-function taskEvent(args: string[] = []): void {
+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) { usageFailure('task ref and event are required'); return; }
+  if (args.length < 2 || !internalHandlerRoute('task-event', 'event', args[1] ? 'event' : '')) { usageFailure('task ref and event are required'); return; }
   const request: TaskEventRequest = { taskRef: args[0]!, event: args[1]!, agent: '' };
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
@@ -66,14 +71,14 @@ function taskEvent(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => {
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, async () => {
       let current = applyTaskEvent(request, { lockAlreadyHeld: true });
       const values = request as Record<string, unknown>;
       if (current.status !== 'failed' || !values.overrideTicket) return current;
       if (!values.overrideTarget || !values.overrideScope) {
         return { ...current, humanOverride: { status: 'failed', error: { code: 'OVERRIDE_PAYLOAD_INVALID', message: 'override ticket requires target and scope' } } } as typeof current & { humanOverride: unknown };
       }
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef: request.taskRef,
         ticketId: String(values.overrideTicket),
         failureId: failureId('task-event', current.error?.code ?? 'EVENT_TRANSITION_INVALID'),