@fitlab-ai/agent-infra 0.9.7 → 0.9.9

package/lib/internal/task-finalization.ts

@@ -0,0 +1,68 @@
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
+import { applyTaskFinalization } from '../task/finalization.ts';
+import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
+import { verifyTaskEvent } from '../task/verification.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
+
+type FinalizationError = Readonly<{ code: string; message: string; retryable: boolean }>;
+
+function envelope(
+  status: 'completed' | 'failed' | 'blocked' | 'unknown',
+  changed: boolean,
+  accepted: boolean,
+  result: ReturnType<typeof applyTaskFinalization> | null,
+  error: FinalizationError | null
+): string {
+  return `${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`;
+}
+
+function exitCode(status: 'completed' | 'failed' | 'blocked' | 'unknown'): number {
+  return status === 'completed' ? 0 : status === 'blocked' ? 2 : 1;
+}
+
+function fail(message: string): void {
+  const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message, retryable: false };
+  process.stdout.write(envelope('failed', false, false, null, error));
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskFinalization(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
+    fail('task ref, complete intent, and --agent are required');
+    return;
+  }
+  const agent = normalizeAgentToken(args[3]);
+  if (!agent) {
+    fail(`invalid --agent: ${AGENT_USAGE_HINT}`);
+    return;
+  }
+  let repoRoot: string;
+  try {
+    repoRoot = detectRepoRoot();
+  } catch (error) {
+    const detail = { code: 'REPO_ROOT_NOT_FOUND', message: error instanceof Error ? error.message : String(error), retryable: false };
+    process.stdout.write(envelope('failed', false, true, null, detail));
+    process.exitCode = 1;
+    return;
+  }
+  const resolved = resolveTaskRef(args[0], { repoRoot });
+  if (!resolved.ok) {
+    const detail = { code: resolved.code, message: resolved.message, retryable: false };
+    process.stdout.write(envelope('failed', false, true, null, detail));
+    process.exitCode = 1;
+    return;
+  }
+  const result = applyTaskFinalization(
+    { taskRef: resolved.taskId, intent: 'complete', agent },
+    { repoRoot, preflight: (request, options) => verifyTaskEvent(
+      { ...request, event: 'complete-task.hard-preflight' }, options
+    ) }
+  );
+  process.stdout.write(envelope(result.status, result.changed, true, result, result.error));
+  process.exitCode = exitCode(result.status);
+}
+
+export { taskFinalization };

package/lib/internal/task-ledger.ts

@@ -2,14 +2,17 @@ import fs from 'node:fs';
 
 import { applyLedgerIntent } from '../task/ledger-intents.ts';
 import type { LedgerIntent } from '../task/ledger-intents.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { isReviewStage, parseLedger, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
 const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, stage-status\n`;
 const FLAGS: Record<string, string> = {
   '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
   '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
   '--status': 'status', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation'
+  , '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['ordinal', 'round']);
 const BOOLEAN = new Set(['needsImplementation']);
@@ -58,11 +61,16 @@ function taskLedger(args: string[] = []): void {
     'finding-review': ['needsImplementation'],
     'decision-upsert': ['needsImplementation']
   };
-  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...(optional[kind] ?? [])]);
+  const overrideFields = kind === 'stage-status' || kind === 'decision-next-id'
+    ? []
+    : ['overrideTicket', 'overrideTarget', 'overrideScope'];
+  const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind]!, ...(optional[kind] ?? []), ...overrideFields]);
   const unexpected = Object.keys(values).find((key) => !allowed.has(key));
   const missing = required[kind]!.find((key) => values[key] === undefined);
   if (unexpected) { usageFailure(`${kind} does not accept '${unexpected}'`); return; }
   if (missing) { usageFailure(`${kind} requires '${missing}'`); return; }
+  const dryRunConflict = overrideDryRunConflict(values);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
   if (kind === 'stage-status') {
     if (!isReviewStage(String(values.stage))) { usageFailure(`stage-status requires a valid review stage`); return; }
     const resolved = resolveTaskRef(taskRef);
@@ -87,9 +95,45 @@ function taskLedger(args: string[] = []): void {
     }
     return;
   }
-  const result = applyLedgerIntent(values as LedgerIntent);
-  process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  const lockResolved = resolveTaskRef(taskRef);
+  if (!lockResolved.ok) { usageFailure(lockResolved.message); return; }
+  let result;
+  let humanOverride: unknown = null;
+  try {
+    result = withTaskExecutionLock(lockResolved.repoRoot, lockResolved.taskId, `task-ledger.${kind}`, () => {
+      let current = applyLedgerIntent(values as LedgerIntent);
+      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('ledger-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
+        target: String(values.overrideTarget),
+        scope: String(values.overrideScope)
+      }, {
+        effectExecutor: (capability) => {
+          const retried = applyLedgerIntent(values as LedgerIntent, { manualOverride: capability });
+          current = retried;
+          return retried.status === 'failed'
+            ? { code: 'OVERRIDE_EFFECT_FAILED', message: `${retried.error?.code ?? 'LEDGER_FAILED'}: ${retried.error?.message ?? 'manual ledger 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 { taskLedger };

package/lib/internal/task-lifecycle.ts

@@ -1,14 +1,16 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
+import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { applyTaskLifecycle, lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import type { TaskLifecycleRequest } from '../task/lifecycle.ts';
-import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\n`;
+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 FLAGS: Record<string, string> = {
   '--agent': 'agent', '--reason': 'reason', '--unblock-condition': 'unblockCondition',
   '--note': 'note', '--alert-number': 'alertNumber', '--staging-dir': 'stagingDir',
-  '--issue-number': 'issueNumber'
+  '--issue-number': 'issueNumber', '--override-ticket': 'overrideTicket',
+  '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 
 function usageFailure(message: string): void {
@@ -39,19 +41,61 @@ function taskLifecycle(args: string[] = []): void {
   const agent = normalizeAgentToken(String(values.agent ?? ''));
   if (!agent) { usageFailure(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
-  const resolved = resolveTaskRef(String(values.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;
+  const dryRunConflict = overrideDryRunConflict(values);
+  if (dryRunConflict) { usageFailure(dryRunConflict.message); return; }
+  let repoRoot: string;
+  let taskId: string;
+  if (values.intent === 'restore') {
+    // restore's precondition is that the task does NOT exist locally yet (it only lives
+    // in a staging dir), so resolveTaskRef's existence check is inapplicable here; identity
+    // is guaranteed by applyTaskLifecycle's own full-TASK-id check plus staging validation.
+    try {
+      repoRoot = detectRepoRoot();
+    } catch (error) {
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'REPO_ROOT_NOT_FOUND', message: error instanceof Error ? error.message : String(error) } })}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    taskId = String(values.taskRef);
+  } else {
+    const resolved = resolveTaskRef(String(values.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;
+    }
+    repoRoot = resolved.repoRoot;
+    taskId = resolved.taskId;
   }
-  let result: ReturnType<typeof applyTaskLifecycle>;
+  let result: ReturnType<typeof applyTaskLifecycle> & { humanOverride?: unknown };
   try {
     result = withTaskExecutionLock(
-      resolved.repoRoot,
-      resolved.taskId,
+      repoRoot,
+      taskId,
       `task-lifecycle.${String(values.intent)}`,
-      () => applyTaskLifecycle(values as TaskLifecycleRequest)
+      () => {
+        const lifecycleResult = applyTaskLifecycle(values as TaskLifecycleRequest);
+        if (lifecycleResult.status !== 'failed' || !values.overrideTicket) return lifecycleResult;
+        if (!values.overrideTarget || !values.overrideScope) {
+          return {
+            ...lifecycleResult,
+            error: { code: 'OVERRIDE_PAYLOAD_INVALID', message: 'override ticket requires --override-target and --override-scope' }
+          };
+        }
+        const override = consumeHumanOverride({
+          taskRef: String(values.taskRef),
+          ticketId: String(values.overrideTicket),
+          failureId: failureId('lifecycle.apply', lifecycleResult.error?.code ?? 'LIFECYCLE_FAILED'),
+          target: String(values.overrideTarget),
+          scope: String(values.overrideScope),
+          intent: String(values.intent) as TaskLifecycleRequest['intent'],
+          ...(values.alertNumber ? { alertNumber: Number(values.alertNumber) } : {}),
+          ...(values.issueNumber ? { issueNumber: Number(values.issueNumber) } : {}),
+          ...(values.stagingDir ? { stagingDir: String(values.stagingDir) } : {})
+        });
+        if (override.status === 'failed') return { ...lifecycleResult, humanOverride: override };
+        return { ...lifecycleResult, ...override, humanOverride: override, error: null };
+      }
     );
   } catch (error) {
     if (!(error instanceof TaskExecutionLockError)) throw error;

package/lib/internal/task-orchestration.ts

@@ -1,31 +1,23 @@
-import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 import {
-  abortCommitIntent,
   activateMatchingOrchestrationDelegation,
   activateOrchestrationDelegation,
   advanceOrchestration,
   awaitOrchestrationDelegationActivation,
-  beginCommitIntent,
   beginOrResumeOrchestration,
-  checkpointCommitIntent,
-  completeCommitIntent,
   dispatchOrchestrationDelegation,
+  OrchestrationStateError,
   pauseOrchestration,
-  recoverCommitIntent,
   recoverPreparedOrchestrationDelegation,
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
   sealOrchestrationDelegation,
-  startCommitAttempt,
-  statusCommitIntent,
-  statusOrchestration,
-  terminateCommitAttempt
+  statusOrchestration
 } from '../task/orchestration.ts';
 import { prepareCodexOrchestrationDelegation } from '../task/codex-orchestration.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
 import type { AgentClientId } from '../agent-clients/types.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|dispatch|await-activation|recover-prepared|hook-start|hook-stop|advance|pause|status|commit-start|commit-begin|commit-checkpoint|commit-complete|commit-recover|commit-abort|commit-terminate|commit-status> [options]\n';
+const USAGE = 'Usage: agent-infra-internal task-orchestration <task-ref|auto> <begin-or-resume|route|prepare|dispatch|await-activation|recover-prepared|hook-start|hook-stop|advance|pause|status> [options]\n';
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({
@@ -48,23 +40,15 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
   const [taskRef, intent] = args;
   if (![
     'begin-or-resume', 'route', 'prepare', 'dispatch', 'await-activation', 'recover-prepared',
-    'hook-start', 'hook-stop', 'advance', 'pause', 'status',
-    'commit-start', 'commit-begin', 'commit-checkpoint', 'commit-complete', 'commit-recover', 'commit-abort', 'commit-terminate', 'commit-status'
+    'hook-start', 'hook-stop', 'advance', 'pause', 'status'
   ].includes(intent!)) {
     usageFailure(`unknown intent '${intent}'`);
     return;
   }
   const values: Record<string, string> = {};
   const seen = new Set<string>();
-  let orchestrated = false;
   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; }
-      seen.add(flag);
-      orchestrated = true;
-      continue;
-    }
     if (![
       '--max-steps', '--executor-model', '--executor-reasoning-effort',
       '--reviewer-model', '--reviewer-reasoning-effort',
@@ -74,8 +58,7 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
       '--native-agent', '--child-id', '--spawn-mode', '--actual-model', '--actual-reasoning-effort',
       '--model-fallback-reason', '--reasoning-effort-fallback-reason',
       '--exit-code', '--after-fingerprint', '--changed-paths', '--code', '--message', '--recoverable', '--agent',
-      '--baseline-head', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
-      , '--attempt', '--git-worktree-root'
+      '--git-worktree-root'
     ].includes(flag)) {
       usageFailure(`unknown option '${flag}'`);
       return;
@@ -92,26 +75,6 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
     }
     values[flag] = value;
   }
-  const commitIntentFlags: Record<string, readonly string[]> = {
-    'commit-start': ['--agent', '--git-worktree-root'],
-    'commit-begin': ['--agent', '--baseline-head', '--attempt', '--orchestrated', '--git-worktree-root'],
-    'commit-checkpoint': ['--token', '--kind', '--head', '--remote', '--ref', '--git-worktree-root'],
-    'commit-complete': ['--token', '--agent', '--git-worktree-root'],
-    'commit-recover': ['--agent', '--git-worktree-root'],
-    'commit-abort': ['--token', '--expected-head', '--git-worktree-root'],
-    'commit-terminate': ['--attempt', '--agent', '--code', '--git-worktree-root'],
-    'commit-status': ['--git-worktree-root']
-  };
-  if (intent! in commitIntentFlags) {
-    const allowed = commitIntentFlags[intent!]!;
-    const invalid = [...seen].find((flag) => !allowed.includes(flag));
-    if (invalid) { usageFailure(`intent '${intent}' does not accept '${invalid}'`); return; }
-  } else {
-    const commitOnly = [...seen].find((flag) => [
-      '--orchestrated', '--baseline-head', '--attempt', '--token', '--kind', '--head', '--remote', '--ref', '--expected-head'
-    ].includes(flag));
-    if (commitOnly) { usageFailure(`intent '${intent}' does not accept '${commitOnly}'`); return; }
-  }
   const requireValues = (flags: string[]) => flags.find((flag) => values[flag] === undefined);
   const coreOptions = values['--git-worktree-root'] === undefined
     ? {}
@@ -121,66 +84,8 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
     return;
   }
   let result;
-  if (intent === 'commit-start') {
-    const missing = requireValues(['--agent']);
-    if (missing) { usageFailure(`intent 'commit-start' requires '${missing}'`); return; }
-    const agent = normalizeAgentToken(values['--agent']!);
-    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = startCommitAttempt(taskRef!, { agent }, coreOptions);
-  } else if (intent === 'commit-begin') {
-    const missing = requireValues(['--agent', '--baseline-head', '--attempt']);
-    if (missing) { usageFailure(`intent 'commit-begin' requires '${missing}'`); return; }
-    const agent = normalizeAgentToken(values['--agent']!);
-    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = beginCommitIntent(taskRef!, {
-      agent, orchestrated, baselineHead: values['--baseline-head']!, attempt: values['--attempt']!
-    }, coreOptions);
-  } else if (intent === 'commit-checkpoint') {
-    const missing = requireValues(['--token', '--kind', '--head']);
-    if (missing) { usageFailure(`intent 'commit-checkpoint' requires '${missing}'`); return; }
-    if (!['committed', 'pushed'].includes(values['--kind']!)) {
-      usageFailure('--kind must be committed or pushed'); return;
-    }
-    if (values['--kind'] === 'pushed') {
-      const pushedMissing = requireValues(['--remote', '--ref']);
-      if (pushedMissing) { usageFailure(`pushed checkpoint requires '${pushedMissing}'`); return; }
-    } else if (values['--remote'] !== undefined || values['--ref'] !== undefined) {
-      usageFailure('committed checkpoint does not accept --remote or --ref'); return;
-    }
-    result = checkpointCommitIntent(taskRef!, {
-      token: values['--token']!, kind: values['--kind'] as 'committed' | 'pushed',
-      head: values['--head']!, remote: values['--remote'], ref: values['--ref']
-    }, coreOptions);
-  } else if (intent === 'commit-complete') {
-    const missing = requireValues(['--token', '--agent']);
-    if (missing) { usageFailure(`intent 'commit-complete' requires '${missing}'`); return; }
-    const agent = normalizeAgentToken(values['--agent']!);
-    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = completeCommitIntent(taskRef!, { token: values['--token']!, agent }, coreOptions);
-  } else if (intent === 'commit-recover') {
-    const missing = requireValues(['--agent']);
-    if (missing) { usageFailure(`intent 'commit-recover' requires '${missing}'`); return; }
-    const agent = normalizeAgentToken(values['--agent']!);
-    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    result = recoverCommitIntent(taskRef!, { agent }, coreOptions);
-  } else if (intent === 'commit-abort') {
-    const missing = requireValues(['--token', '--expected-head']);
-    if (missing) { usageFailure(`intent 'commit-abort' requires '${missing}'`); return; }
-    result = abortCommitIntent(taskRef!, { token: values['--token']!, expectedHead: values['--expected-head']! }, coreOptions);
-  } else if (intent === 'commit-terminate') {
-    const missing = requireValues(['--attempt', '--agent', '--code']);
-    if (missing) { usageFailure(`intent 'commit-terminate' requires '${missing}'`); return; }
-    const agent = normalizeAgentToken(values['--agent']!);
-    if (!agent) { usageFailure(`invalid --agent '${values['--agent']}': ${AGENT_USAGE_HINT}`); return; }
-    if (!/^[A-Z][A-Z0-9_]{2,63}$/.test(values['--code']!)) {
-      usageFailure('--code must be a stable uppercase identifier'); return;
-    }
-    result = terminateCommitAttempt(taskRef!, {
-      attempt: values['--attempt']!, agent, code: values['--code']!
-    }, coreOptions);
-  } else if (intent === 'commit-status') {
-    result = statusCommitIntent(taskRef!, coreOptions);
-  } else if (intent === 'begin-or-resume') {
+  try {
+  if (intent === 'begin-or-resume') {
     const missing = requireValues(['--client']);
     if (missing) { usageFailure(`intent 'begin-or-resume' requires '${missing}'`); return; }
     const maxSteps = values['--max-steps'] === undefined ? undefined : Number(values['--max-steps']);
@@ -247,12 +152,12 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
   } else if (intent === 'hook-start') {
     const missing = requireValues([
       ...(taskRef === 'auto' ? ['--client'] : []),
-      '--native-agent', '--child-id', '--parent-id', '--spawn-mode'
+      '--native-agent', '--child-id', '--parent-id'
     ]);
     if (missing) { usageFailure(`intent 'hook-start' requires '${missing}'`); return; }
     const event = {
       nativeAgent: values['--native-agent']!, childId: values['--child-id']!,
-      parentId: values['--parent-id']!, spawnMode: values['--spawn-mode']!,
+      parentId: values['--parent-id']!, spawnMode: values['--spawn-mode'],
       actualModel: values['--actual-model'],
       actualReasoningEffort: values['--actual-reasoning-effort'],
       modelFallbackReason: values['--model-fallback-reason'],
@@ -266,7 +171,11 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
       const missing = requireValues(['--client', '--native-agent', '--child-id']);
       if (missing) { usageFailure(`intent 'hook-stop' requires '${missing}'`); return; }
       result = sealMatchingOrchestrationDelegation(values['--client'] as AgentClientId, {
-        nativeAgent: values['--native-agent']!, childId: values['--child-id']!
+        nativeAgent: values['--native-agent']!, childId: values['--child-id']!,
+        actualModel: values['--actual-model'],
+        actualReasoningEffort: values['--actual-reasoning-effort'],
+        modelFallbackReason: values['--model-fallback-reason'],
+        reasoningEffortFallbackReason: values['--reasoning-effort-fallback-reason']
       }, coreOptions);
     } else {
       const missing = requireValues(['--child-id', '--exit-code', '--after-fingerprint']);
@@ -276,7 +185,11 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
       result = sealOrchestrationDelegation(taskRef!, {
         childId: values['--child-id']!, exitCode,
         afterFingerprint: values['--after-fingerprint']!,
-        changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : []
+        changedPaths: values['--changed-paths'] ? values['--changed-paths']!.split(',').filter(Boolean) : [],
+        actualModel: values['--actual-model'],
+        actualReasoningEffort: values['--actual-reasoning-effort'],
+        modelFallbackReason: values['--model-fallback-reason'],
+        reasoningEffortFallbackReason: values['--reasoning-effort-fallback-reason']
       }, coreOptions);
     }
   } else if (intent === 'advance') {
@@ -287,7 +200,19 @@ async function taskOrchestration(args: string[] = []): Promise<void> {
     if (!['true', 'false'].includes(values['--recoverable']!)) { usageFailure('--recoverable must be true or false'); return; }
     result = pauseOrchestration(taskRef!, values['--code']!, values['--message']!, values['--recoverable'] === 'true', coreOptions);
   }
-  process.stdout.write(`${JSON.stringify(result)}\n`);
+  } catch (error) {
+    if (!(error instanceof OrchestrationStateError)) throw error;
+    result = {
+      status: 'failed' as const,
+      changed: false,
+      taskId: error.taskId,
+      run: null,
+      next: null,
+      error: { code: error.code, message: error.message }
+    };
+  }
+  const output = result;
+  process.stdout.write(`${JSON.stringify(output)}\n`);
   if (result.status === 'failed') process.exitCode = 1;
 }
 

package/lib/internal/task-override.ts

@@ -0,0 +1,138 @@
+import {
+  consumeHumanOverride,
+  diagnoseHumanOverrideForTask,
+  issueHumanOverride
+} from '../task/human-override.ts';
+import type { ConsumeHumanOverrideRequest, HumanOverrideRequest } 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-override <task-ref> <diagnose|issue|consume> [options]
+
+Options: --failure-id <id> --target <target> --operator <operator> --reason <reason> --scope <scope>
+         --intent <lifecycle-intent> --alert-number <N> --issue-number <N> --staging-dir <path>
+         --expires-at <timestamp> --ticket <ticket-id> --pr-number <N>
+`;
+
+const FLAGS: Record<string, string> = {
+  '--failure-id': 'failureId',
+  '--target': 'target',
+  '--operator': 'operator',
+  '--reason': 'reason',
+  '--scope': 'scope',
+  '--intent': 'intent',
+  '--failure-digest': 'failureDigest',
+  '--expires-at': 'expiresAt',
+  '--ticket': 'ticketId',
+  '--facts': 'observedFacts',
+  '--alert-number': 'alertNumber',
+  '--issue-number': 'issueNumber',
+  '--pr-number': 'pullRequestNumber',
+  '--staging-dir': 'stagingDir'
+};
+
+function usageFailure(message: string): void {
+  process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'OVERRIDE_PAYLOAD_INVALID', message } })}\n`);
+  process.stderr.write(USAGE);
+  process.exitCode = 1;
+}
+
+function taskOverride(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const [taskRef, operation] = args;
+  if (!taskRef || !operation || !['diagnose', 'issue', 'consume'].includes(operation)) {
+    usageFailure('task ref and a valid operation are required');
+    return;
+  }
+  const values: Record<string, unknown> = { taskRef };
+  const seen = new Set<string>();
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    const key = FLAGS[flag];
+    if (!key) { usageFailure(`unknown option '${flag}'`); return; }
+    if (seen.has(flag)) { usageFailure(`duplicate option '${flag}'`); return; }
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) { usageFailure(`option '${flag}' requires a value`); return; }
+    seen.add(flag);
+    values[key] = key === 'observedFacts' ? value.split(',').map((fact) => fact.trim()).filter(Boolean)
+      : key === 'alertNumber' || key === 'issueNumber' || key === 'pullRequestNumber' ? Number(value) : value;
+  }
+
+  const required: Record<string, string[]> = {
+    diagnose: [],
+    issue: ['failureId', 'target', 'operator', 'reason', 'scope', 'expiresAt'],
+    consume: ['failureId', 'target', 'scope', 'ticketId']
+  };
+  const missing = required[operation]!.find((key) => values[key] === undefined);
+  if (missing) { usageFailure(`${operation} requires '--${missing.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}'`); return; }
+
+  const resolved = resolveTaskRef(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;
+  try {
+    if (operation === 'diagnose') {
+      result = diagnoseHumanOverrideForTask(
+        taskRef,
+        values.failureId ? String(values.failureId) : undefined,
+        values.target ? String(values.target) : undefined
+      );
+    } else if (operation === 'issue') {
+      result = withTaskExecutionLock(
+        resolved.repoRoot,
+        resolved.taskId,
+        'task-override.issue',
+        () => issueHumanOverride({
+          taskRef,
+          failureId: String(values.failureId),
+          target: String(values.target),
+          operator: String(values.operator),
+          reason: String(values.reason),
+          scope: String(values.scope),
+          expiresAt: String(values.expiresAt),
+          ...(values.intent ? { intent: String(values.intent) as HumanOverrideRequest['intent'] } : {}),
+          ...(values.alertNumber !== undefined ? { alertNumber: Number(values.alertNumber) } : {}),
+          ...(values.issueNumber !== undefined ? { issueNumber: Number(values.issueNumber) } : {}),
+          ...(values.pullRequestNumber !== undefined ? { pullRequestNumber: Number(values.pullRequestNumber) } : {}),
+          ...(values.stagingDir ? { stagingDir: String(values.stagingDir) } : {}),
+          ...(values.failureDigest ? { failureDigest: String(values.failureDigest) } : {})
+        } satisfies HumanOverrideRequest)
+      );
+    } else {
+        result = withTaskExecutionLock(
+        resolved.repoRoot,
+        resolved.taskId,
+        'task-override.consume',
+        () => consumeHumanOverride({
+          taskRef,
+          ticketId: String(values.ticketId),
+          failureId: String(values.failureId),
+          target: String(values.target),
+          scope: String(values.scope),
+          ...(values.intent ? { intent: String(values.intent) as ConsumeHumanOverrideRequest['intent'] } : {}),
+          ...(values.alertNumber !== undefined ? { alertNumber: Number(values.alertNumber) } : {}),
+          ...(values.issueNumber !== undefined ? { issueNumber: Number(values.issueNumber) } : {}),
+          ...(values.pullRequestNumber !== undefined ? { pullRequestNumber: Number(values.pullRequestNumber) } : {}),
+          ...(values.stagingDir ? { stagingDir: String(values.stagingDir) } : {}),
+          ...(values.failureDigest ? { failureDigest: String(values.failureDigest) } : {}),
+          ...(values.observedFacts ? { observedFacts: values.observedFacts as string[] } : {})
+        } satisfies ConsumeHumanOverrideRequest)
+      );
+    }
+  } catch (cause) {
+    if (cause instanceof TaskExecutionLockError) {
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: cause.code, message: cause.message } })}\n`);
+      process.exitCode = 1;
+      return;
+    }
+    throw cause;
+  }
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
+}
+
+export { taskOverride };