@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/lib/task/orchestration.ts

@@ -10,13 +10,20 @@ import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.
 import { resolveTaskRef } from './resolve-ref.ts';
 import {
   activateDelegation,
+  abortPreparedDelegation,
   completeDelegationStage,
   consumeDelegation,
+  dispatchDelegation,
   managedDelegationRole,
   prepareDelegation,
   sealDelegation
 } from './delegation-receipts.ts';
-import type { DelegationReceipt, DelegationRole, DelegationStage } from './delegation-receipts.ts';
+import type {
+  DelegationLifecycleProvenance,
+  DelegationReceipt,
+  DelegationRole,
+  DelegationStage
+} from './delegation-receipts.ts';
 import { normalizeAgentClients } from '../agent-clients/config.ts';
 import { inspectPlatformPullRequest } from '../platform/pull-requests.ts';
 import {
@@ -39,6 +46,7 @@ import type { RepositorySnapshot } from './workspace-snapshot.ts';
 import type { WorkspaceSnapshotContext } from './workspace-snapshot.ts';
 import { assertGitRepositoryBinding } from '../git/worktree-identity.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
+import { hasActiveCodexLifecycleEvidence } from '../agent-clients/adapters/codex-lifecycle/store.ts';
 import {
   CommitIntentError,
   commitIntentPath,
@@ -74,7 +82,7 @@ type ModelPolicySource = Readonly<{
   client: AgentClientId;
   resolvedAt: string;
 }>;
-type OrchestrationRecovery = Readonly<{
+type ModelPolicyRecovery = Readonly<{
   code: 'MODEL_POLICY_SUPPLEMENTED';
   recoveredAt: string;
   previousSchemaVersion: 1;
@@ -85,6 +93,44 @@ type OrchestrationRecovery = Readonly<{
   pendingDelegation: false;
   resultingStatus: OrchestrationStatus;
 }>;
+type ClientCapabilityRecovery = Readonly<{
+  code: 'CLIENT_CAPABILITY_ENABLED';
+  recoveredAt: string;
+  previousSchemaVersion: 2;
+  previousStatus: 'paused';
+  previousPause: Readonly<{ code: 'ORCHESTRATION_CLIENT_UNSUPPORTED'; message: string; recoverable: boolean }>;
+  client: 'codex';
+  guards: Readonly<{
+    stepCount: 0;
+    nextStage: null;
+    baselineEmpty: true;
+    receiptCount: 0;
+    pendingDelegation: false;
+    commitAuthorizationUnused: true;
+    completionEvidenceAbsent: true;
+    commitIntentAbsent: true;
+  }>;
+  resultingStatus: 'running';
+}>;
+type SchemaMigrationRecovery = Readonly<{
+  code: 'SCHEMA_V3_MIGRATED';
+  recoveredAt: string;
+  previousSchemaVersion: 2;
+  previousStatus: 'paused';
+  previousPause: Readonly<{ code: string; message: string; recoverable: boolean }>;
+  guards: Readonly<{
+    stepCount: 0;
+    nextStage: null;
+    baselineEmpty: true;
+    receiptCount: 0;
+    pendingDelegation: false;
+    commitAuthorizationUnused: true;
+    completionEvidenceAbsent: true;
+    commitIntentAbsent: true;
+  }>;
+  resultingStatus: 'running';
+}>;
+type OrchestrationRecovery = ModelPolicyRecovery | ClientCapabilityRecovery | SchemaMigrationRecovery;
 type CleanCompletionEvidence = Readonly<{
   kind: 'reviewed-head-clean';
   observedAt: string;
@@ -96,7 +142,7 @@ type CleanCompletionEvidence = Readonly<{
   prHead: string;
 }>;
 type OrchestrationRun = Readonly<{
-  schemaVersion: 1 | 2;
+  schemaVersion: 1 | 2 | 3;
   taskId: string;
   runId: string;
   status: OrchestrationStatus;
@@ -173,6 +219,9 @@ type OrchestrationOptions = {
   diffWorkspace?: (repoRoot: string, before: string, after: string) => string[];
   supportsLifecycleDelegation?: (client: AgentClientId) => boolean;
   token?: () => string;
+  monotonicNow?: () => number;
+  sleep?: (milliseconds: number) => Promise<void>;
+  hasActiveLifecycleEvidence?: (receipt: DelegationReceipt) => boolean;
 };
 
 type CommitIntentResult = Readonly<{
@@ -218,7 +267,7 @@ function readRun(taskDir: string): OrchestrationRun | null {
   const file = orchestrationPath(taskDir);
   if (!fs.existsSync(file)) return null;
   const run = JSON.parse(fs.readFileSync(file, 'utf8')) as OrchestrationRun;
-  if (run.schemaVersion !== 2 || !isV2Policy(run.modelPolicy)) return run;
+  if (![2, 3].includes(run.schemaVersion) || !isV2Policy(run.modelPolicy)) return run;
   return {
     ...run,
     modelPolicy: {
@@ -309,7 +358,7 @@ function commitFinalizationView(inspection: CommitFinalizationInspection): NonNu
 
 function validCommitRun(run: OrchestrationRun | null, taskId: string): run is OrchestrationRun {
   return run !== null
-    && [1, 2].includes(run.schemaVersion)
+    && [1, 2, 3].includes(run.schemaVersion)
     && run.taskId === taskId
     && ['running', 'paused', 'completed'].includes(run.status)
     && Array.isArray(run.receipts)
@@ -369,6 +418,38 @@ function resolveProjectPolicy(repoRoot: string, client: AgentClientId): Orchestr
   return normalizeAgentClients(raw).state[client].orchestration;
 }
 
+function canRecoverCodexUnsupportedPause(run: OrchestrationRun, taskDir: string): boolean {
+  return run.schemaVersion === 2
+    && run.status === 'paused'
+    && run.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+    && run.modelPolicySource?.client === 'codex'
+    && run.stepCount === 0
+    && run.nextStage === null
+    && run.baseline === ''
+    && run.pendingDelegation === null
+    && run.receipts.length === 0
+    && run.commitAuthorization?.issuedAt === null
+    && run.commitAuthorization?.consumedAt === null
+    && run.completionEvidence == null
+    && !fs.existsSync(commitIntentPath(taskDir))
+    && (run.recoveryHistory ?? []).every((entry) => entry.code === 'MODEL_POLICY_SUPPLEMENTED');
+}
+
+function canMigrateRecoverableV2Pause(run: OrchestrationRun, taskDir: string): boolean {
+  return run.schemaVersion === 2
+    && run.status === 'paused'
+    && run.pause?.recoverable === true
+    && run.stepCount === 0
+    && run.nextStage === null
+    && run.baseline === ''
+    && run.pendingDelegation === null
+    && run.receipts.length === 0
+    && run.commitAuthorization?.issuedAt === null
+    && run.commitAuthorization?.consumedAt === null
+    && run.completionEvidence == null
+    && !fs.existsSync(commitIntentPath(taskDir));
+}
+
 function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
@@ -383,7 +464,7 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
   }
   if (existing) {
     if (
-      ![1, 2].includes(existing.schemaVersion)
+      ![1, 2, 3].includes(existing.schemaVersion)
       || !Array.isArray(existing.receipts)
       || !Object.prototype.hasOwnProperty.call(existing, 'pendingDelegation')
     ) {
@@ -392,7 +473,7 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
     if (existing.status === 'completed' && existing.schemaVersion === 1) {
       return { status: 'completed', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
     }
-    if (existing.schemaVersion === 2) {
+    if (existing.schemaVersion === 2 || existing.schemaVersion === 3) {
       const policyError = validateModelPolicy(isV2Policy(existing.modelPolicy) ? existing.modelPolicy : undefined);
       if (
         policyError
@@ -400,11 +481,18 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
         || !isAgentClientId(existing.modelPolicySource.client)
         || !Array.isArray(existing.recoveryHistory)
       ) {
-        return failed('ORCHESTRATION_STATE_INVALID', 'schemaVersion 2 orchestration state is incomplete', resolved.taskId);
+        return failed('ORCHESTRATION_STATE_INVALID', `schemaVersion ${existing.schemaVersion} orchestration state is incomplete`, resolved.taskId);
       }
       if (existing.status === 'completed') {
         return { status: 'completed', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
       }
+      if (existing.schemaVersion === 2 && existing.status === 'running') {
+        return failed(
+          'ORCHESTRATION_STATE_INVALID',
+          'active schemaVersion 2 runs cannot be advanced by lifecycle protocol v3',
+          resolved.taskId
+        );
+      }
       if (existing.modelPolicySource.client !== options.client) {
         return failed('ORCHESTRATION_CLIENT_MISMATCH', 'provided client does not match the persisted run policy source', resolved.taskId);
       }
@@ -415,8 +503,77 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
           return failed('ORCHESTRATION_MODEL_POLICY_MISMATCH', 'provided model policy does not match the persisted run policy', resolved.taskId);
         }
       }
+      if (existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED') {
+        if (!canRecoverCodexUnsupportedPause(existing, resolved.taskDir)) {
+          return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
+        }
+        const now = (options.now ?? (() => new Date().toISOString()))();
+        const previousPause = existing.pause as ClientCapabilityRecovery['previousPause'];
+        const recovery: ClientCapabilityRecovery = {
+          code: 'CLIENT_CAPABILITY_ENABLED',
+          recoveredAt: now,
+          previousSchemaVersion: 2,
+          previousStatus: 'paused',
+          previousPause,
+          client: 'codex',
+          guards: {
+            stepCount: 0,
+            nextStage: null,
+            baselineEmpty: true,
+            receiptCount: 0,
+            pendingDelegation: false,
+            commitAuthorizationUnused: true,
+            completionEvidenceAbsent: true,
+            commitIntentAbsent: true
+          },
+          resultingStatus: 'running'
+        };
+        const resumed = withUpdatedRun(existing, {
+          schemaVersion: 3,
+          status: 'running',
+          pause: null,
+          recoveryHistory: Object.freeze([...(existing.recoveryHistory ?? []), recovery])
+        }, () => now);
+        saveRun(resolved.taskDir, resumed);
+        return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
+      }
       if (existing.status === 'paused' && existing.pause?.recoverable && existing.pendingDelegation === null) {
-        const resumed = withUpdatedRun(existing, { status: 'running', pause: null });
+        if (existing.schemaVersion === 2 && !canMigrateRecoverableV2Pause(existing, resolved.taskDir)) {
+          const paused = withUpdatedRun(existing, {
+            pause: {
+              code: 'ORCHESTRATION_SCHEMA_MIGRATION_REQUIRED',
+              message: 'schemaVersion 2 recoverable pause contains execution evidence and cannot migrate automatically',
+              recoverable: false
+            }
+          });
+          saveRun(resolved.taskDir, paused);
+          return { status: 'paused', changed: true, taskId: resolved.taskId, run: paused, next: null, error: null };
+        }
+        const now = (options.now ?? (() => new Date().toISOString()))();
+        const recovery: SchemaMigrationRecovery | null = existing.schemaVersion === 2 ? {
+          code: 'SCHEMA_V3_MIGRATED',
+          recoveredAt: now,
+          previousSchemaVersion: 2,
+          previousStatus: 'paused',
+          previousPause: existing.pause,
+          guards: {
+            stepCount: 0,
+            nextStage: null,
+            baselineEmpty: true,
+            receiptCount: 0,
+            pendingDelegation: false,
+            commitAuthorizationUnused: true,
+            completionEvidenceAbsent: true,
+            commitIntentAbsent: true
+          },
+          resultingStatus: 'running'
+        } : null;
+        const resumed = withUpdatedRun(existing, {
+          schemaVersion: 3,
+          status: 'running',
+          pause: null,
+          ...(recovery ? { recoveryHistory: Object.freeze([...(existing.recoveryHistory ?? []), recovery]) } : {})
+        }, () => now);
         saveRun(resolved.taskDir, resumed);
         return { status: 'running', changed: true, taskId: resolved.taskId, run: resumed, next: null, error: null };
       }
@@ -492,7 +649,7 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
     };
     const recovered: OrchestrationRun = Object.freeze({
       ...existing,
-      schemaVersion: 2,
+      schemaVersion: 3,
       status: resultingStatus,
       modelPolicy: policy!,
       modelPolicySource: source,
@@ -523,7 +680,7 @@ function beginOrResumeOrchestration(taskRef: string, options: OrchestrationOptio
   const now = (options.now ?? (() => new Date().toISOString()))();
   const source: ModelPolicySource = { kind: sourceKind, client: options.client, resolvedAt: now };
   const run: OrchestrationRun = {
-    schemaVersion: 2,
+    schemaVersion: 3,
     taskId: resolved.taskId,
     runId: (options.id ?? randomUUID)(),
     status: 'running',
@@ -1262,7 +1419,12 @@ function statusOrchestration(taskRef: string, options: OrchestrationOptions = {}
 
 function prepareOrchestrationDelegationUnlocked(
   taskRef: string,
-  input: Readonly<{ client: AgentClientId; requestedModel?: string; requestedReasoningEffort?: string }>,
+  input: Readonly<{
+    client: AgentClientId;
+    requestedModel?: string;
+    requestedReasoningEffort?: string;
+    lifecycleProvenance?: DelegationLifecycleProvenance;
+  }>,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
@@ -1284,6 +1446,9 @@ function prepareOrchestrationDelegationUnlocked(
   }
   const run = readRun(resolved.taskDir);
   if (!run || run.status !== 'running') return failed('ORCHESTRATION_RUN_NOT_RUNNING', 'a running orchestration is required', resolved.taskId);
+  if (run.schemaVersion !== 3) {
+    return failed('ORCHESTRATION_STATE_INVALID', 'delegation preparation requires orchestration schemaVersion 3', resolved.taskId);
+  }
   if (!isV2Policy(run.modelPolicy)) return failed('ORCHESTRATION_MODEL_EVIDENCE_MISSING', 'running orchestration has no persisted model policy', resolved.taskId);
   if (run.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_BUSY', 'the run already has a pending delegation', resolved.taskId);
   const repositoryPending = matchingDelegations(() => true, options);
@@ -1300,6 +1465,9 @@ function prepareOrchestrationDelegationUnlocked(
   if (!validModel(input.requestedReasoningEffort)) {
     return failed('ORCHESTRATION_REQUESTED_REASONING_EFFORT_REQUIRED', 'prepare requires the exact requested reasoning effort', resolved.taskId);
   }
+  if (input.client === 'codex' && !input.lifecycleProvenance) {
+    return failed('ORCHESTRATION_CODEX_PROVENANCE_REQUIRED', 'Codex prepare requires lifecycle provenance', resolved.taskId);
+  }
   const expectedPolicy = run.modelPolicy[next.role];
   if (input.requestedModel !== expectedPolicy.model) {
     return failed('ORCHESTRATION_REQUESTED_MODEL_MISMATCH', `requested model does not match the persisted ${next.role} model`, resolved.taskId);
@@ -1328,8 +1496,9 @@ function prepareOrchestrationDelegationUnlocked(
     requestedModel: input.requestedModel,
     requestedReasoningEffort: input.requestedReasoningEffort,
     workspaceSnapshotScope: 'task',
+    lifecycleProvenance: input.lifecycleProvenance ?? null,
     beforeFingerprint
-  }, { id: options.id, now: options.now });
+  }, { id: options.id, now: options.now, monotonicNow: options.monotonicNow });
   const updated = withUpdatedRun(run, {
     nextStage: next.stage,
     pendingDelegation: receipt,
@@ -1343,7 +1512,12 @@ function prepareOrchestrationDelegationUnlocked(
 
 function prepareOrchestrationDelegation(
   taskRef: string,
-  input: Readonly<{ client: AgentClientId; requestedModel?: string; requestedReasoningEffort?: string }>,
+  input: Readonly<{
+    client: AgentClientId;
+    requestedModel?: string;
+    requestedReasoningEffort?: string;
+    lifecycleProvenance?: DelegationLifecycleProvenance;
+  }>,
   options: OrchestrationOptions = {}
 ): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
@@ -1366,6 +1540,51 @@ function prepareOrchestrationDelegation(
   }
 }
 
+function dispatchOrchestrationDelegationUnlocked(
+  taskRef: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  const run = readRun(resolved.taskDir);
+  if (!run?.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+  if (run.schemaVersion !== 3 || run.status !== 'running') {
+    return failed('ORCHESTRATION_STATE_INVALID', 'spawn dispatch requires a running schemaVersion 3 orchestration', resolved.taskId);
+  }
+  const result = dispatchDelegation(run.pendingDelegation, {
+    now: options.now,
+    monotonicNow: options.monotonicNow
+  });
+  if (!result.ok) return pauseOrchestration(taskRef, result.code, result.message, true, options);
+  const updated = withUpdatedRun(run, { pendingDelegation: result.receipt });
+  saveRun(resolved.taskDir, updated);
+  return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
+}
+
+function dispatchOrchestrationDelegation(
+  taskRef: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    return withTaskExecutionLock(
+      resolved.repoRoot,
+      '__repository__',
+      'task-orchestration.dispatch.repository',
+      () => withTaskExecutionLock(
+        resolved.repoRoot,
+        resolved.taskId,
+        'task-orchestration.dispatch.task',
+        () => dispatchOrchestrationDelegationUnlocked(taskRef, options)
+      )
+    );
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) return failed(error.code, error.message, resolved.taskId);
+    throw error;
+  }
+}
+
 function matchingDelegations(
   predicate: (receipt: DelegationReceipt) => boolean,
   options: OrchestrationOptions
@@ -1377,7 +1596,7 @@ function matchingDelegations(
     .filter((entry) => entry.isDirectory())
     .flatMap((entry) => {
       const run = readRun(path.join(activeRoot, entry.name));
-      if (!run?.pendingDelegation) return [];
+      if (run?.schemaVersion !== 3 || run.status !== 'running' || !run.pendingDelegation) return [];
       const receipt = run.pendingDelegation;
       return predicate(receipt)
         ? [{ taskId: entry.name, run }]
@@ -1399,6 +1618,33 @@ function uniqueMatchingDelegation(
   return matches[0]!;
 }
 
+function hasActivatableOrchestrationDelegation(
+  client: AgentClientId,
+  childId: string,
+  options: OrchestrationOptions = {}
+): boolean {
+  return matchingDelegations(
+    (receipt) => receipt.client === client && (
+      receipt.status === 'prepared'
+      || (receipt.childId === childId && ['activated', 'stage-completed'].includes(receipt.status))
+    ),
+    options
+  ).length > 0;
+}
+
+function hasSealableOrchestrationDelegation(
+  client: AgentClientId,
+  childId: string,
+  options: OrchestrationOptions = {}
+): boolean {
+  return matchingDelegations(
+    (receipt) => receipt.client === client
+      && receipt.childId === childId
+      && ['stage-completed', 'sealed'].includes(receipt.status),
+    options
+  ).length > 0;
+}
+
 function activateMatchingOrchestrationDelegation(
   client: AgentClientId,
   event: Parameters<typeof activateDelegation>[1],
@@ -1411,13 +1657,44 @@ function activateMatchingOrchestrationDelegation(
     (receipt) => receipt.status === 'prepared',
     options
   );
-  if ('status' in matched) return matched;
+  if ('status' in matched) {
+    if (matched.error?.code !== 'ORCHESTRATION_DELEGATION_MISSING') return matched;
+    const replay = uniqueMatchingDelegation(
+      client,
+      (receipt) => receipt.childId === event.childId && ['activated', 'stage-completed'].includes(receipt.status),
+      options
+    );
+    if ('status' in replay) return matched;
+    const receipt = replay.run.pendingDelegation!;
+    const sameEvidence = receipt.parentId === event.parentId
+      && receipt.spawnMode === event.spawnMode
+      && receipt.actualModel === event.actualModel
+      && receipt.actualReasoningEffort === event.actualReasoningEffort
+      && receipt.modelFallbackReason === (event.modelFallbackReason ?? null)
+      && receipt.reasoningEffortFallbackReason === (event.reasoningEffortFallbackReason ?? null)
+      && receipt.hostEvidence?.hookDefinitionHash === event.hostEvidence?.hookDefinitionHash;
+    if (!sameEvidence) {
+      return pauseOrchestration(replay.taskId, 'DELEGATION_REPLAY_CONFLICT', 'replayed native start evidence conflicts with the active receipt', true, options);
+    }
+    return { status: replay.run.status, changed: false, taskId: replay.taskId, run: replay.run, next: null, error: null };
+  }
   if (matched.run.receipts.some((receipt) => receipt.childId === event.childId)) {
     return pauseOrchestration(matched.taskId, 'DELEGATION_IDENTITY_REUSED', 'native child identity was already used by this run', true, options);
   }
   return activateOrchestrationDelegation(matched.taskId, event, options);
 }
 
+function pauseMatchingOrchestrationDelegation(
+  client: AgentClientId,
+  code: string,
+  message: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const matched = uniqueMatchingDelegation(client, () => true, options);
+  if ('status' in matched) return matched;
+  return pauseOrchestration(matched.taskId, code, message, true, options);
+}
+
 function sealMatchingOrchestrationDelegation(
   client: AgentClientId,
   event: Readonly<{ nativeAgent: string; childId: string }>,
@@ -1462,6 +1739,96 @@ function sealMatchingOrchestrationDelegation(
   }
 }
 
+function sealMatchingOrchestrationDelegationWithHostEvidence(
+  client: AgentClientId,
+  event: Readonly<{ nativeAgent: string; childId: string }>,
+  consumeEvidence: (receipt: DelegationReceipt) => Readonly<{
+    stopRevision: number;
+    consumer: string;
+    consumedAt: string;
+  }>,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const role = managedDelegationRole(event.nativeAgent);
+  if (!role) return failed('DELEGATION_IGNORED', `subagent '${event.nativeAgent}' is not lifecycle-managed`);
+  const matched = uniqueMatchingDelegation(
+    client,
+    (receipt) => (
+      (receipt.status === 'stage-completed' || receipt.status === 'sealed')
+      && receipt.childId === event.childId
+    ),
+    options
+  );
+  if ('status' in matched) return matched;
+  const receipt = matched.run.pendingDelegation!;
+  if (receipt.status === 'sealed') {
+    return reconcileMatchingOrchestrationDelegation(client, event.childId, options);
+  }
+  if (receipt.role !== role) {
+    return pauseOrchestration(matched.taskId, 'DELEGATION_ROLE_MISMATCH', `managed role ${role} does not match ${receipt.role}`, true, options);
+  }
+  const repoRoot = options.repoRoot ?? process.cwd();
+  try {
+    const gitRoot = gitRootFor(repoRoot, options);
+    const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
+    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+      gitRoot,
+      stateRoot: repoRoot,
+      taskId: snapshotTaskId
+    });
+    const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(gitRoot, receipt.beforeFingerprint, afterFingerprint);
+    const baseEvent = { childId: event.childId, exitCode: 0, afterFingerprint, changedPaths };
+    const validated = sealDelegation(receipt, baseEvent, { now: options.now, requireHostEvidence: false });
+    if (!validated.ok) {
+      return pauseOrchestration(matched.taskId, validated.code, validated.message, true, options);
+    }
+    const hostEvidence = consumeEvidence(receipt);
+    const sealed = sealDelegation(receipt, { ...baseEvent, hostEvidence }, { now: options.now });
+    if (!sealed.ok) return pauseOrchestration(matched.taskId, sealed.code, sealed.message, true, options);
+    const resolved = resolveTaskRef(matched.taskId, { repoRoot });
+    if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+    const updated = withUpdatedRun(matched.run, { pendingDelegation: sealed.receipt }, options.now);
+    saveRun(resolved.taskDir, updated);
+    return { status: 'running', changed: true, taskId: matched.taskId, run: updated, next: null, error: null };
+  } catch (error) {
+    return pauseOrchestration(
+      matched.taskId,
+      'ORCHESTRATION_CODEX_EVIDENCE_FAILED',
+      error instanceof Error ? error.message : String(error),
+      true,
+      options
+    );
+  }
+}
+
+function reconcileMatchingOrchestrationDelegation(
+  client: AgentClientId,
+  childId: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const matched = uniqueMatchingDelegation(
+    client,
+    (receipt) => receipt.childId === childId,
+    options
+  );
+  if ('status' in matched) return matched;
+  const receipt = matched.run.pendingDelegation!;
+  if (
+    receipt.status !== 'sealed'
+    || receipt.hostEvidence?.consumer !== receipt.id
+    || receipt.hostEvidence.consumedAt === null
+  ) {
+    return pauseOrchestration(
+      matched.taskId,
+      'ORCHESTRATION_CODEX_RECONCILIATION_FAILED',
+      'Codex native spawn did not produce one sealed receipt with consumed host evidence',
+      true,
+      options
+    );
+  }
+  return { status: matched.run.status, changed: false, taskId: matched.taskId, run: matched.run, next: null, error: null };
+}
+
 function activateOrchestrationDelegation(
   taskRef: string,
   event: Parameters<typeof activateDelegation>[1],
@@ -1471,7 +1838,14 @@ function activateOrchestrationDelegation(
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
   const run = readRun(resolved.taskDir);
   if (!run?.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
-  const result = activateDelegation(run.pendingDelegation, event, { now: options.now });
+  if (run.schemaVersion !== 3) return failed('ORCHESTRATION_STATE_INVALID', 'active delegation requires schemaVersion 3', resolved.taskId);
+  if (run.status !== 'running') {
+    return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
+  }
+  const result = activateDelegation(run.pendingDelegation, event, {
+    now: options.now,
+    monotonicNow: options.monotonicNow
+  });
   if (!result.ok) {
     if (result.code === 'DELEGATION_IGNORED') return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
     return pauseOrchestration(taskRef, result.code, result.message, true, options);
@@ -1481,6 +1855,153 @@ function activateOrchestrationDelegation(
   return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
 
+async function awaitOrchestrationDelegationActivation(
+  taskRef: string,
+  event: OrchestrationStageIdentity,
+  options: OrchestrationOptions = {}
+): Promise<OrchestrationResult> {
+  const sleep = options.sleep
+    ?? ((milliseconds: number) => new Promise<void>((resolve) => setTimeout(resolve, milliseconds)));
+  while (true) {
+    const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+    if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+    const run = readRun(resolved.taskDir);
+    if (!run?.pendingDelegation) {
+      return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+    }
+    if (run.schemaVersion !== 3) {
+      return failed('ORCHESTRATION_STATE_INVALID', 'activation barrier requires schemaVersion 3', resolved.taskId);
+    }
+    const receipt = run.pendingDelegation;
+    const matches = receipt.stage === event.stage
+      && receipt.round === event.round
+      && receipt.artifact === event.artifact
+      && receipt.role === event.role;
+    if (!matches) {
+      return pauseOrchestration(
+        taskRef,
+        'ORCHESTRATION_PROVENANCE_MISMATCH',
+        'activation barrier identity does not match the pending delegation',
+        true,
+        options
+      );
+    }
+    if (receipt.status === 'activated' || receipt.status === 'stage-completed') {
+      return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
+    }
+    if (run.status !== 'running') {
+      return { status: run.status, changed: false, taskId: resolved.taskId, run, next: null, error: null };
+    }
+    if (receipt.status !== 'prepared') {
+      return pauseOrchestration(
+        taskRef,
+        'ORCHESTRATION_ACTIVATION_STATE_INVALID',
+        `activation barrier found receipt status '${receipt.status}'`,
+        true,
+        options
+      );
+    }
+    if (
+      receipt.activationDeadlineAt == null
+      || !Number.isFinite(Date.parse(receipt.activationDeadlineAt))
+    ) {
+      return pauseOrchestration(
+        taskRef,
+        'ORCHESTRATION_DELEGATION_NOT_DISPATCHED',
+        'activation barrier was entered before the native spawn dispatch boundary',
+        true,
+        options
+      );
+    }
+    if (Date.parse((options.now ?? (() => new Date().toISOString()))()) >= Date.parse(receipt.activationDeadlineAt)) {
+      return pauseOrchestration(
+        taskRef,
+        'ORCHESTRATION_ACTIVATION_TIMEOUT',
+        'fresh child did not receive trusted activation evidence before the deadline',
+        true,
+        options
+      );
+    }
+    await sleep(100);
+  }
+}
+
+function recoverPreparedOrchestrationDelegation(
+  taskRef: string,
+  options: OrchestrationOptions = {}
+): OrchestrationResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-orchestration.recover-prepared', () => {
+      const run = readRun(resolved.taskDir);
+      const receipt = run?.pendingDelegation;
+      if (!run || !receipt) {
+        return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+      }
+      if (receipt.status !== 'prepared') {
+        return failed('ORCHESTRATION_PREPARED_RECOVERY_UNSAFE', 'only a never-activated prepared receipt can recover', resolved.taskId);
+      }
+      const wallNow = Date.parse((options.now ?? (() => new Date().toISOString()))());
+      if (
+        receipt.activationDeadlineAt != null
+        && Number.isFinite(Date.parse(receipt.activationDeadlineAt))
+        && wallNow <= Date.parse(receipt.activationDeadlineAt)
+      ) {
+        return failed('ORCHESTRATION_PREPARED_RECOVERY_EARLY', 'prepared receipt activation deadline has not elapsed', resolved.taskId);
+      }
+      const activeLifecycleEvidence = options.hasActiveLifecycleEvidence?.(receipt)
+        ?? (
+          receipt.client === 'codex'
+          && receipt.lifecycleProvenance
+          && hasActiveCodexLifecycleEvidence(
+            path.join(resolved.repoRoot, '.agents', 'workspace', '.runtime', 'codex-lifecycle'),
+            {
+              nativeAgent: `agent-infra-lifecycle-${receipt.role}`,
+              hookDefinitionHash: receipt.lifecycleProvenance.hookDefinitionHash
+            }
+          )
+        );
+      if (activeLifecycleEvidence) {
+        return failed(
+          'ORCHESTRATION_PREPARED_RECOVERY_ACTIVE_EVIDENCE',
+          'active Codex lifecycle evidence blocks prepared receipt recovery',
+          resolved.taskId
+        );
+      }
+      if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+        return failed('ORCHESTRATION_PREPARED_RECOVERY_UNSAFE', 'active commit intent blocks prepared recovery', resolved.taskId);
+      }
+      const current = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+        gitRoot: gitRootFor(resolved.repoRoot, options),
+        stateRoot: resolved.repoRoot,
+        taskId: receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null
+      });
+      if (current !== receipt.beforeFingerprint) {
+        return failed('ORCHESTRATION_PREPARED_RECOVERY_DRIFT', 'workspace changed after delegation preparation', resolved.taskId);
+      }
+      const aborted = abortPreparedDelegation(receipt);
+      if (!aborted.ok) return failed(aborted.code, aborted.message, resolved.taskId);
+      const updated = withUpdatedRun(run, {
+        status: 'running',
+        pause: null,
+        nextStage: null,
+        pendingDelegation: null,
+        receipts: Object.freeze([...run.receipts, aborted.receipt])
+      }, options.now);
+      saveRun(resolved.taskDir, updated);
+      return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
+    });
+  } catch (error) {
+    if (error instanceof TaskExecutionLockError) return failed(error.code, error.message, resolved.taskId);
+    return failed(
+      'ORCHESTRATION_PREPARED_RECOVERY_FAILED',
+      error instanceof Error ? error.message : String(error),
+      resolved.taskId
+    );
+  }
+}
+
 function completeOrchestrationStage(
   taskRef: string,
   event: Parameters<typeof completeDelegationStage>[1],
@@ -1490,6 +2011,7 @@ function completeOrchestrationStage(
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
   const run = readRun(resolved.taskDir);
   if (!run) return { status: 'running', changed: false, taskId: resolved.taskId, run: null, next: null, error: null };
+  if (run.schemaVersion !== 3) return failed('ORCHESTRATION_STATE_INVALID', 'stage completion requires schemaVersion 3', resolved.taskId);
   if (!run.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_MISSING', 'active run has no pending delegation', resolved.taskId);
   const result = completeDelegationStage(run.pendingDelegation, event);
   if (!result.ok) return pauseOrchestration(taskRef, result.code, result.message, true, options);
@@ -1512,6 +2034,7 @@ function inspectOrchestrationStage(
     return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
   }
   if (!run) return failed('ORCHESTRATION_RUN_MISSING', 'no orchestration run exists', resolved.taskId);
+  if (run.schemaVersion !== 3) return failed('ORCHESTRATION_STATE_INVALID', 'stage inspection requires schemaVersion 3', resolved.taskId);
   const receipt = run.pendingDelegation;
   if (
     !receipt
@@ -1570,6 +2093,7 @@ function sealOrchestrationDelegation(
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
   const run = readRun(resolved.taskDir);
   if (!run?.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+  if (run.schemaVersion !== 3) return failed('ORCHESTRATION_STATE_INVALID', 'delegation sealing requires schemaVersion 3', resolved.taskId);
   const result = sealDelegation(run.pendingDelegation, event, { now: options.now });
   if (!result.ok) return pauseOrchestration(taskRef, result.code, result.message, true, options);
   const updated = withUpdatedRun(run, { pendingDelegation: result.receipt });
@@ -1582,6 +2106,7 @@ function advanceOrchestration(taskRef: string, options: OrchestrationOptions = {
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
   const run = readRun(resolved.taskDir);
   if (!run?.pendingDelegation) return failed('ORCHESTRATION_DELEGATION_MISSING', 'no pending delegation exists', resolved.taskId);
+  if (run.schemaVersion !== 3) return failed('ORCHESTRATION_STATE_INVALID', 'orchestration advance requires schemaVersion 3', resolved.taskId);
   const result = consumeDelegation(run.pendingDelegation, { now: options.now });
   if (!result.ok) return pauseOrchestration(taskRef, result.code, result.message, true, options);
   const completed = result.receipt.stage === 'commit';
@@ -1618,6 +2143,7 @@ function pauseOrchestration(
 export {
   activateMatchingOrchestrationDelegation,
   activateOrchestrationDelegation,
+  awaitOrchestrationDelegationActivation,
   advanceOrchestration,
   abortCommitIntent,
   beginCommitIntent,
@@ -1626,15 +2152,22 @@ export {
   commitOrchestrationStageCompletion,
   completeCommitIntent,
   completeOrchestrationStage,
+  dispatchOrchestrationDelegation,
   inspectOrchestrationStage,
+  hasActivatableOrchestrationDelegation,
+  hasSealableOrchestrationDelegation,
   orchestrationPath,
+  pauseMatchingOrchestrationDelegation,
   pauseOrchestration,
   planOrchestrationStageCompletion,
   prepareOrchestrationDelegation,
   readRun,
+  reconcileMatchingOrchestrationDelegation,
   recoverCommitIntent,
+  recoverPreparedOrchestrationDelegation,
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
+  sealMatchingOrchestrationDelegationWithHostEvidence,
   sealOrchestrationDelegation,
   startCommitAttempt,
   statusCommitIntent,
@@ -1650,5 +2183,6 @@ export type {
   OrchestrationRun,
   OrchestrationStageCompletion,
   OrchestrationStageIdentity,
-  OrchestrationStatus
+  OrchestrationStatus,
+  OrchestrationOptions
 };