@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/lib/decide.ts

@@ -2,6 +2,9 @@ import { VERSION } from './version.ts';
 import { parseTaskScope } from './task/command-options.ts';
 import { applyHumanDecision } from './task/decision-intents.ts';
 import { canonicalTimestamp } from './task/write.ts';
+import { consumeHumanOverride, failureId } from './task/human-override.ts';
+import { resolveTaskRef } from './task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task/task-execution-lock.ts';
 
 type DecideOptions = {
   repoRoot?: string;
@@ -9,23 +12,33 @@ type DecideOptions = {
   version?: string;
 };
 
-function parseDecisionParts(parts: string[]): { decision: string; needsImplementation: boolean | undefined } {
+function parseDecisionParts(parts: string[]): { decision: string; needsImplementation: boolean | undefined; overrideTicket?: string; overrideTarget?: string; overrideScope?: string } {
   const decision: string[] = [];
   let needsImplementation: boolean | undefined;
+  let overrideTicket: string | undefined;
+  let overrideTarget: string | undefined;
+  let overrideScope: string | undefined;
   for (let index = 0; index < parts.length; index += 1) {
-    if (parts[index] !== '--needs-implementation') {
+    const part = parts[index];
+    if (part === '--needs-implementation') {
+      if (needsImplementation !== undefined) throw new Error("duplicate option '--needs-implementation'");
+      const value = parts[++index];
+      if (value !== 'true' && value !== 'false') {
+        throw new Error("--needs-implementation must be 'true' or 'false'");
+      }
+      needsImplementation = value === 'true';
+    } else if (part === '--override-ticket' || part === '--override-target' || part === '--override-scope') {
+      const value = parts[++index];
+      if (!value) throw new Error(`${part} requires a value`);
+      if (part === '--override-ticket') overrideTicket = value;
+      else if (part === '--override-target') overrideTarget = value;
+      else overrideScope = value;
+    } else {
       decision.push(parts[index]!);
-      continue;
     }
-    if (needsImplementation !== undefined) throw new Error("duplicate option '--needs-implementation'");
-    const value = parts[++index];
-    if (value !== 'true' && value !== 'false') {
-      throw new Error("--needs-implementation must be 'true' or 'false'");
-    }
-    needsImplementation = value === 'true';
   }
   if (decision.length === 0) throw new Error('decision content is required');
-  return { decision: decision.join(' '), needsImplementation };
+  return { decision: decision.join(' '), needsImplementation, overrideTicket, overrideTarget, overrideScope };
 }
 
 export async function decide(args: string[], options: DecideOptions = {}): Promise<number> {
@@ -64,17 +77,49 @@ export async function decide(args: string[], options: DecideOptions = {}): Promi
   try {
     const parsedDecision = parseDecisionParts(decisionParts);
     const now = (options.now ?? canonicalTimestamp)();
-    const result = applyHumanDecision({
+    const request = {
       taskRef, selector, decision: parsedDecision.decision,
       needsImplementation: parsedDecision.needsImplementation
-    }, {
+    };
+    const writeOptions = {
       repoRoot: options.repoRoot,
       metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
-    });
+    };
+    const resolved = taskRef ? resolveTaskRef(taskRef, { repoRoot: options.repoRoot }) : null;
+    let result;
+    const execute = () => {
+      let current = applyHumanDecision(request, writeOptions);
+      if (current.status !== 'failed' || !parsedDecision.overrideTicket) return current;
+      if (!parsedDecision.overrideTarget || !parsedDecision.overrideScope) throw new Error('override ticket requires --override-target and --override-scope');
+      const consumed = consumeHumanOverride({
+        taskRef: resolved?.ok ? resolved.taskId : String(taskRef ?? ''),
+        ticketId: parsedDecision.overrideTicket,
+        failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: parsedDecision.overrideTarget,
+        scope: parsedDecision.overrideScope
+      }, {
+        ...writeOptions,
+        effectExecutor: (capability) => {
+          const retried = applyHumanDecision(request, { ...writeOptions, manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no decision effect was committed' : `${retried.error?.code ?? 'DECISION_FAILED'}: ${retried.error?.message ?? 'manual decision effect failed'}` }
+            : null;
+        }
+      });
+      if (consumed.status === 'failed') throw new Error(consumed.error.message);
+      return current;
+    };
+    result = resolved?.ok
+      ? withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute)
+      : execute();
     if (result.error) throw new Error(result.error.message);
     return 0;
   } catch (error) {
-    process.stderr.write(`Error: ${error instanceof Error ? error.message : String(error)}\n`);
+    const message = error instanceof TaskExecutionLockError
+      ? `${error.code}: ${error.message}`
+      : error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Error: ${message}\n`);
     return 1;
   }
 }

package/lib/git/workflow.ts

@@ -105,7 +105,7 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
   return { status: 'applied' as const, changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' as const }, { name: 'commit', status: 'applied' as const }], error: null };
 }
 
-function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string[] }, runner: GitRunner = defaultRunner) {
+function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string[]; expectedSha?: string }, runner: GitRunner = defaultRunner) {
   if (!input.remote || input.refs.length === 0) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [], error: { code: 'GIT_PUSH_INPUT_INVALID', message: 'Remote and refs are required' } };
   const operations: GitOperation[] = [];
   for (const ref of input.refs) {
@@ -120,7 +120,16 @@ function pushGitRefs(input: { cwd: string; remote: string; refs: readonly string
     }
     const canonical = ref.startsWith('refs/') ? ref : `refs/heads/${ref}`;
     const remoteFact = run(runner, input.cwd, ['ls-remote', '--exit-code', input.remote, canonical]);
-    operations.push({ name: 'push', ref, status: remoteFact.status === 0 ? 'applied' : 'failed', message: remoteFact.status === 0 ? undefined : 'Remote ref verification failed' });
+    const remoteSha = remoteFact.status === 0 ? remoteFact.stdout.trim().split(/\s+/)[0] ?? null : null;
+    const verified = remoteFact.status === 0 && (!input.expectedSha || remoteSha === input.expectedSha);
+    operations.push({
+      name: 'push',
+      ref,
+      status: verified ? 'applied' : 'failed',
+      message: verified ? undefined : input.expectedSha
+        ? `Remote ref verification failed: expected ${input.expectedSha}, received ${remoteSha ?? 'unavailable'}`
+        : 'Remote ref verification failed'
+    });
   }
   const failures = operations.filter((item) => item.status === 'failed').length;
   return { status: failures === 0 ? 'applied' as const : failures === operations.length ? 'failed' as const : 'degraded' as const, changed: failures < operations.length, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations, error: failures ? { code: 'GIT_PUSH_PARTIAL', message: `${failures} ref push operation(s) failed` } : null };

package/lib/init.ts

@@ -249,7 +249,7 @@ async function cmdInit(): Promise<void> {
     agentClients: serializeAgentClients(defaultState)
   };
 
-  if (sandboxEngine) config.sandbox.engine = sandboxEngine;
+  if (sandboxEngine) config.sandbox.engine = { [currentPlatform]: sandboxEngine };
   if (templateSources.length > 0) config.templates = { sources: templateSources };
   if (skillSources.length > 0) config.skills = { sources: skillSources };
 

package/lib/internal/codex-lifecycle.ts

@@ -14,6 +14,7 @@ import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-l
 import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
 import type { CodexLifecycleEvent } from '../agent-clients/adapters/codex-lifecycle/evidence.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { hasSealableOrchestrationDelegation } from '../task/orchestration.ts';
 import {
   activateCodexOrchestrationDelegation,
   activateCodexSpawnDelegation,
@@ -100,7 +101,7 @@ function hookDefinitionHash(): string {
 function controllerBinding(taskId: string) {
   const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
   if (!contextPath) return undefined;
-  const context = verifyCodexSandboxControllerContext(contextPath, taskId, { repoRoot: process.cwd() });
+  const context = verifyCodexSandboxControllerContext(contextPath, { repoRoot: process.cwd() });
   return {
     instanceDigest: context.controllerInstanceDigest,
     controlGeneration: context.controlGeneration
@@ -139,7 +140,8 @@ function recordFromPayload(phase: string, payload: unknown): CodexLifecycleEvent
     sessionId: text('sessionId'),
     turnId: text('turnId'),
     childThreadId: text('childThreadId'),
-    nativeAgent: text('nativeAgent')
+    nativeAgent: text('nativeAgent'),
+    source: 'hook'
   };
   if (phase === 'subagent-stop') return {
     type: 'hook-stop',
@@ -326,8 +328,17 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       }
       const result = store.apply(event);
       if (parsed.values['--bridge'] === 'true' && event.type === 'hook-stop') {
-        const bridged = await sealCodexOrchestrationDelegation(event.childThreadId, { store });
-        outputBridgeResult(bridged);
+        if (!hasSealableOrchestrationDelegation('codex', event.childThreadId, { repoRoot: process.cwd() })) {
+          output({ status: 'ignored', changed: false, evidence: null, diagnostics: [], error: null });
+          return;
+        }
+        output({
+          status: result.state.status,
+          changed: true,
+          evidence: result.state,
+          diagnostics: [],
+          error: result.state.error
+        });
         return;
       }
       output({ status: result.state.status, changed: true, evidence: result.state, diagnostics: [], error: result.state.error });
@@ -350,7 +361,9 @@ async function codexLifecycle(args: string[] = []): Promise<void> {
       return;
     }
     if (parsed.operation === 'resolve-stop') {
-      const terminal = await resolveCodexTerminal(childThreadId);
+      const stopTurnId = store.read(childThreadId).state.stop?.turnId;
+      if (!stopTurnId) throw new Error('Codex lifecycle stop hook is not available');
+      const terminal = await resolveCodexTerminal(childThreadId, stopTurnId);
       const latest = store.apply(terminal);
       if (latest.state.status !== 'stop-ready') {
         throw new Error(`Codex lifecycle stop evidence is not ready (status=${latest.state.status})`);

package/lib/internal/codex-sandbox-controller.ts

@@ -26,8 +26,6 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
     return null;
   }
   const allowed = new Set([
-    '--task-id',
-    '--task-ref',
     '--context',
     '--executor-model',
     '--executor-reasoning-effort',
@@ -37,6 +35,11 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
   const values: Record<string, string> = {};
   for (let index = 1; index < args.length; index += 1) {
     const flag = args[index]!;
+    if (flag === '--task-id' || flag.startsWith('--task-id=')
+      || flag === '--task-ref' || flag.startsWith('--task-ref=')) {
+      fail('CODEX_SANDBOX_CONTROLLER_IDENTITY_OPTION_UNSUPPORTED', 'controller task identity options are not supported', 2);
+      return null;
+    }
     const value = args[++index];
     if (!allowed.has(flag) || Object.hasOwn(values, flag) || !value || value.startsWith('--')) {
       fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', `invalid option '${flag}'`, 2);
@@ -50,17 +53,12 @@ function parse(args: string[]): Readonly<{ operation: string; values: Readonly<R
 async function codexSandboxController(args: string[] = []): Promise<void> {
   const parsed = parse(args);
   if (!parsed || process.exitCode) return;
-  const taskId = parsed.values['--task-id'];
-  if (!taskId) {
-    fail('CODEX_SANDBOX_CONTROLLER_PAYLOAD_INVALID', '--task-id is required', 2);
-    return;
-  }
   try {
     if (parsed.operation === 'verify-context') {
       const contextPath = parsed.values['--context']
         ?? process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
       if (!contextPath) throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_MISSING');
-      const context = verifyCodexSandboxControllerContext(contextPath, taskId);
+      const context = verifyCodexSandboxControllerContext(contextPath);
       process.stdout.write(`${JSON.stringify({
         status: 'ready',
         changed: false,
@@ -77,8 +75,6 @@ async function codexSandboxController(args: string[] = []): Promise<void> {
       })}\n`);
       return;
     }
-    const taskRef = parsed.values['--task-ref'];
-    if (!taskRef) throw new Error('CODEX_SANDBOX_CONTROLLER_TASK_REF_REQUIRED');
     const policy = [
       '--executor-model',
       '--executor-reasoning-effort',
@@ -90,8 +86,6 @@ async function codexSandboxController(args: string[] = []): Promise<void> {
       throw new Error('CODEX_SANDBOX_CONTROLLER_MODEL_POLICY_INVALID');
     }
     const exitCode = await runCodexSandboxController({
-      taskId,
-      taskRef,
       executorModel: parsed.values['--executor-model'],
       executorReasoningEffort: parsed.values['--executor-reasoning-effort'],
       reviewerModel: parsed.values['--reviewer-model'],

package/lib/internal/git-workflow.ts

@@ -1,7 +1,8 @@
 import fs from 'node:fs';
-import { commitExplicitPaths, inspectGitWorkflow, pushGitRefs, pushRebasedBranch } from '../git/workflow.ts';
+import { inspectGitWorkflow, pushRebasedBranch } from '../git/workflow.ts';
 import { compareReviewTrees, snapshotReview } from '../git/review-snapshot.ts';
 import { resolvePostReviewGlobs } from '../task/review-fingerprint.ts';
+import { executeCommitOperation } from '../task/commit-operation.ts';
 
 function output(value: unknown): void { process.stdout.write(`${JSON.stringify(value)}\n`); }
 
@@ -18,11 +19,9 @@ function gitWorkflow(args: string[] = []): void {
   else if (action === 'commit') {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
-    result = input ? commitExplicitPaths({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
-  } else if (action === 'push') {
-    const inputIndex = rest.indexOf('--input');
-    const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;
-    result = input ? pushGitRefs({ cwd: cwd ?? process.cwd(), ...input }) : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
+    result = input
+      ? executeCommitOperation({ cwd: cwd ?? process.cwd(), ...input })
+      : { status: 'failed', changed: false, error: { code: 'GIT_INPUT_REQUIRED', message: '--input JSON file is required' } };
   } else if (action === 'push-rebased') {
     const inputIndex = rest.indexOf('--input');
     const input = inputIndex >= 0 && rest[inputIndex + 1] ? JSON.parse(fs.readFileSync(rest[inputIndex + 1]!, 'utf8')) : null;

package/lib/internal/platform-pr.ts

@@ -17,13 +17,13 @@ const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd
        agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
-       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
 `;
 
 const BOOLEAN_FLAGS = new Set(['--draft', '--dry-run', '--metadata', '--closing-issue']);
-const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--pr']);
+const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--pr', '--result']);
 
 function key(flag: string): string {
   return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
@@ -76,9 +76,9 @@ function platformPr(args: string[] = []): void {
     'resolve-external': ['cwd', 'agent', 'pr', 'dryRun'],
     create: ['cwd', 'agent', 'base', 'head', 'titleFile', 'bodyFile', 'draft', 'dryRun'],
     bind: ['cwd', 'agent', 'pr', 'dryRun'],
-    sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'dryRun'],
+    sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'result', 'dryRun'],
     'summary-context': ['cwd'],
-    'summary-sync': ['cwd', 'agent', 'bodyFile', 'dryRun']
+    'summary-sync': ['cwd', 'agent', 'bodyFile', 'result', 'dryRun']
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
@@ -88,6 +88,11 @@ function platformPr(args: string[] = []): void {
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
+  const primaryResult = values.result === undefined ? undefined : values.result;
+  if (primaryResult !== undefined && !['pr_created', 'pr_reused', 'no_op'].includes(primaryResult as string)) {
+    fail('--result must be pr_created, pr_reused, or no_op');
+    return;
+  }
   if (operation === 'resolve-external') {
     const pr = values.pr === undefined ? undefined : Number(values.pr);
     if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) { fail('resolve-external requires a positive --pr'); return; }
@@ -102,13 +107,15 @@ function platformPr(args: string[] = []): void {
   }
   if (operation === 'sync') {
     if (values.metadata !== true && values.closingIssue !== true) { fail('sync requires --metadata or --closing-issue'); return; }
-    finish(syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, dryRun: values.dryRun === true }));
+    if (!primaryResult) { fail('sync requires --result pr_created, pr_reused, or no_op'); return; }
+    finish(syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
     return;
   }
   if (operation === 'summary-sync') {
     if (typeof values.bodyFile !== 'string') { fail('summary-sync requires --body-file'); return; }
+    if (!primaryResult) { fail('summary-sync requires --result pr_created, pr_reused, or no_op'); return; }
     try {
-      finish(syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), dryRun: values.dryRun === true }));
+      finish(syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
     } catch (error) {
       fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     }

package/lib/internal/release-workflow.ts

@@ -25,20 +25,19 @@ type DemoResult = {
   outputPath: string | null;
 };
 
+// The tape is the canonical init interaction contract. Do not hash all of
+// lib/init.ts: non-visual config serialization changes must not re-record it.
 const DEMO_INPUT_PATHS = [
   'assets/demo-init.tape',
   'scripts/demo-regen.sh',
   'scripts/normalize-gif-duration.py',
   'bin/cli.ts',
-  'lib/init.ts',
   'lib/log.ts',
   'lib/prompt.ts',
   'lib/paths.ts',
   'lib/render.ts',
   'lib/builtin-tuis.ts',
-  'lib/sandbox/engines/',
-  'src/sync-templates.js',
-  'templates/'
+  'lib/sandbox/engines/'
 ] as const;
 const DEMO_DIGEST_PATH = 'assets/demo-init.inputs.sha256';
 const DEMO_OUTPUT_PATH = 'assets/demo-init.gif';

package/lib/internal/sandbox-control.ts

@@ -1,6 +1,84 @@
-import { requestSandboxControl, SandboxControlClientError } from '../sandbox/control/client.ts';
+import {
+  requestSandboxControl,
+  requestSandboxTaskFinalization,
+  requestSandboxTaskControl,
+  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 {
+  controllerProofFromContext,
+  verifyCodexSandboxControllerContext
+} from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.ts';
+
+function isCanonicalCodexPrepare(args: readonly string[]): boolean {
+  if (args[1] !== 'prepare') return false;
+  const clients: string[] = [];
+  for (let index = 2; index < args.length; index += 1) {
+    if (args[index] === '--client') clients.push(args[index + 1] ?? '');
+    else if (args[index]?.startsWith('--client=')) clients.push(args[index]!.slice('--client='.length));
+  }
+  return clients.length === 1 && clients[0] === 'codex';
+}
+
+type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
+
+function writeFinalizationEnvelope(
+  status: FinalizationStatus,
+  accepted: boolean,
+  error: { code: string; message: string; retryable: boolean },
+  changed = false,
+  result: unknown = null
+): void {
+  process.stdout.write(`${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`);
+}
+
+function finalizationErrorStatus(error: { retryable: boolean; code: string }): FinalizationStatus {
+  if (error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') return 'unknown';
+  return error.retryable ? 'blocked' : 'failed';
+}
+
+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;
+    writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
+    process.stderr.write(`${error.detail.message}\n`);
+    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
+    };
+    writeFinalizationEnvelope(finalizationErrorStatus(error), error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN', error);
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
+    return;
+  }
+  process.stdout.write(response.stdout);
+  process.stderr.write(response.stderr);
+  process.exitCode = response.exitCode ?? 1;
+}
 
 async function sandboxControl(args: string[]): Promise<void> {
   const [operation, ...rest] = args;
@@ -31,9 +109,21 @@ async function sandboxControl(args: string[]): Promise<void> {
   }
   if (operation === 'client') {
     const [family = '', ...commandArgs] = rest;
+    if (family === 'task-finalization') {
+      sandboxFinalizationClient(commandArgs);
+      return;
+    }
     let response;
     try {
-      response = requestSandboxControl({ family, args: commandArgs });
+      if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
+        const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+        const proof = contextPath
+          ? controllerProofFromContext(verifyCodexSandboxControllerContext(contextPath))
+          : null;
+        response = requestSandboxTaskControl({ family, args: commandArgs, controllerProof: proof });
+      } else {
+        response = requestSandboxControl({ family, args: commandArgs });
+      }
     } catch (error) {
       if (!(error instanceof SandboxControlClientError)) throw error;
       process.stderr.write(`${error.detail.message}\n`);

package/lib/internal/task-activity.ts

@@ -6,6 +6,9 @@ import type {
   PrReviewActivityIntent,
   PrReviewInspectIntent
 } from '../task/activity-intent.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';
 
 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]
@@ -24,13 +27,14 @@ const FLAGS: Record<string, string> = {
   '--minor': 'minor',
   '--outcome': 'outcome',
   '--reason': 'reason'
+  , '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const COMMON = ['agent', 'artifact', 'head'] as const;
 const ALLOWED: Record<string, ReadonlySet<string>> = {
   'pr-review-inspect': new Set(['kind', 'taskRef']),
-  'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun']),
-  'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun']),
-  'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun'])
+  'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']),
+  'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']),
+  'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope'])
 };
 
 function usageFailure(message: string): void {
@@ -83,9 +87,45 @@ function taskActivity(args: string[] = []): void {
   for (const key of operationRequired) {
     if (values[key] === undefined) { usageFailure(`${kind} requires '${key}'`); return; }
   }
-  const result = applyPrReviewActivityIntent(values as PrReviewActivityIntent);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict(values);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { usageFailure(resolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, () => {
+      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({
+        taskRef, ticketId: String(values.overrideTicket),
+        failureId: failureId('activity-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: String(values.overrideTarget), scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyPrReviewActivityIntent(values as PrReviewActivityIntent, { lockAlreadyHeld: true, manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no activity effect was committed' : `${retried.error?.code ?? 'ACTIVITY_FAILED'}: ${retried.error?.message ?? 'manual activity effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
+  const overrideFailed = Boolean(
+    humanOverride && typeof humanOverride === 'object' &&
+    (humanOverride as { status?: unknown }).status === 'failed'
+  );
+  if (result.status === 'failed' || overrideFailed) process.exitCode = 1;
 }
 
 export { taskActivity };

package/lib/internal/task-event.ts

@@ -1,6 +1,9 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import { applyTaskEvent, eventCatalog } from '../task/events.ts';
 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';
 
 const USAGE = `Usage: agent-infra-internal task-event <N | TASK-id> <event> --agent <agent> [event options] [--orchestrated] [--dry-run]
 
@@ -13,7 +16,8 @@ const FLAGS: Record<string, keyof TaskEventRequest> = {
   '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
   '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
   '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
-  '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult'
+  '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult',
+  '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
 
@@ -51,9 +55,54 @@ function taskEvent(args: string[] = []): void {
   const agent = normalizeAgentToken(String(request.agent ?? ''));
   if (!agent) { usageFailure(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`); return; }
   request.agent = agent;
-  const result = applyTaskEvent(request);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const dryRunConflict = overrideDryRunConflict(request as unknown as Record<string, unknown>);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); 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`);
+    process.exitCode = 1;
+    return;
+  }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => {
+      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({
+        taskRef: request.taskRef,
+        ticketId: String(values.overrideTicket),
+        failureId: failureId('task-event', current.error?.code ?? 'EVENT_TRANSITION_INVALID'),
+        target: String(values.overrideTarget),
+        scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyTaskEvent(request, { lockAlreadyHeld: true, manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed' || retried.status === 'planned'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no task event was committed' : `${retried.error?.code ?? 'EVENT_FAILED'}: ${retried.error?.message ?? 'manual task event effect failed'}` }
+            : null;
+        }
+      });
+      humanOverride = consumed;
+      return current;
+    });
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
+  const overrideFailed = Boolean(
+    humanOverride && typeof humanOverride === 'object' &&
+    (humanOverride as { status?: unknown }).status === 'failed'
+  );
+  if (result.status === 'failed' || overrideFailed) process.exitCode = 1;
 }
 
 export { taskEvent };