@fitlab-ai/agent-infra 0.9.7 → 0.9.8

package/lib/agent-clients/adapters/codex-lifecycle/sandbox-controller.ts

@@ -17,6 +17,7 @@ type ControllerControl = Readonly<{
   generation: string;
   channelDir: string;
   statusDir: string;
+  runtimeDir: string;
 }>;
 
 type CodexSandboxControllerContext = Readonly<{
@@ -95,13 +96,38 @@ function controlFromEnvironment(): ControllerControl {
   const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
   const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
   const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
-  if (!token || !generation || !channelDir || !statusDir) {
+  const runtimeDir = process.env.AGENT_INFRA_RUNTIME_DIR;
+  if (!token || !generation || !channelDir || !statusDir || !runtimeDir) {
     throw new Error('CODEX_SANDBOX_CONTROLLER_CONTROL_MISSING');
   }
-  return { token, generation, channelDir, statusDir };
+  return { token, generation, channelDir, statusDir, runtimeDir };
+}
+
+function verifyRuntime(runtimeDir: string): void {
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(runtimeDir);
+  } catch {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+  }
+  const probe = path.join(runtimeDir, `.controller-${process.pid}-${crypto.randomUUID()}.probe`);
+  try {
+    fs.writeFileSync(probe, 'runtime-probe\n', { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+    if (fs.readFileSync(probe, 'utf8') !== 'runtime-probe\n') {
+      throw new Error('probe mismatch');
+    }
+  } catch {
+    throw new Error('CODEX_SANDBOX_CONTROLLER_RUNTIME_UNAVAILABLE');
+  } finally {
+    fs.rmSync(probe, { force: true });
+  }
 }
 
 function verifyControl(taskId: string, control: ControllerControl): void {
+  verifyRuntime(control.runtimeDir);
   let status: ReturnType<typeof readSandboxControlStatus> | null = null;
   let lastError: unknown = null;
   for (let attempt = 0; attempt < 5; attempt += 1) {
@@ -214,6 +240,7 @@ function isolatedEnvironment(
     AGENT_INFRA_CONTROL_GENERATION: control.generation,
     AGENT_INFRA_CONTROL_DIR: control.channelDir,
     AGENT_INFRA_CONTROL_STATUS_DIR: control.statusDir,
+    AGENT_INFRA_RUNTIME_DIR: control.runtimeDir,
     AGENT_INFRA_CODEX_CONTROLLER_CONTEXT: contextPath
   };
 }

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

@@ -11,6 +11,7 @@ import type {
   CodexLifecycleEvent,
   CodexLifecycleState
 } from './evidence.ts';
+import { resolveAgentRuntimeStoreRoot } from '../../../runtime/agent-runtime.ts';
 
 type StoredCodexLifecycle = Readonly<{
   schemaVersion: 1;
@@ -105,7 +106,7 @@ function writeRecord(file: string, record: StoredCodexLifecycle, expectedRevisio
 }
 
 function createCodexLifecycleStore(options: CodexLifecycleStoreOptions) {
-  const root = options.root ?? path.join(process.cwd(), '.agents', 'workspace', '.runtime', 'codex-lifecycle');
+  const root = options.root ?? resolveAgentRuntimeStoreRoot({ store: 'lifecycle' });
   const now = options.now ?? (() => new Date().toISOString());
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
   fs.chmodSync(root, 0o700);

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/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/release-workflow.ts

@@ -36,9 +36,7 @@ const DEMO_INPUT_PATHS = [
   '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/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 };

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

@@ -247,12 +247,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 +266,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 +280,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') {