@fitlab-ai/agent-infra 0.11.11 → 0.11.13

package/dist/lib/agent-clients/adapters/codex-orchestration.js

@@ -0,0 +1,468 @@
+import { preflightCodexLifecycleEvidence, resolveCodexSpawnedChild, resolveCodexTerminal, resolveCodexThread } from './codex-lifecycle/app-server.js';
+import { createCodexLifecycleStore } from './codex-lifecycle/store.js';
+import { computeLifecycleBuildIdentity, } from './codex-lifecycle/build-identity.js';
+import { resolveTaskRef } from '../../task/resolve-ref.js';
+import { activateMatchingOrchestrationDelegation, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, OrchestrationStateError, pauseMatchingOrchestrationDelegation, prepareOrchestrationDelegation, reconcileMatchingOrchestrationDelegation, readDelegationAdapterEvidence, readRun, sealMatchingOrchestrationDelegation } from '../../task/orchestration.js';
+import { managedDelegationRole } from '../../task/delegation-receipts.js';
+import { encodeCodexLifecycleBinding, parseCodexLifecycleBinding, verifyCodexLifecycleTaskBinding } from './codex-lifecycle/binding.js';
+import { reduceCodexLifecycleEvent } from './codex-lifecycle/evidence.js';
+function coreOptions(options) {
+    return {
+        ...options.orchestrationOptions,
+        repoRoot: options.repoRoot ?? options.orchestrationOptions?.repoRoot,
+        taskId: options.orchestrationOptions?.taskId ?? options.store?.taskId ?? undefined
+    };
+}
+function taskRunMatchesReceipt(run, binding, nativeAgent) {
+    const receipt = run?.pendingDelegation;
+    const role = nativeAgent.endsWith('reviewer') ? 'reviewer' : 'executor';
+    return run?.status === 'running'
+        && receipt?.runId === binding.runId
+        && receipt.id === binding.receiptId
+        && receipt.client === 'codex'
+        && receipt.role === role;
+}
+function recordMatchesTaskReceipt(childThreadId, options) {
+    const store = requiredStore(options);
+    let record;
+    try {
+        record = store.read(childThreadId);
+    }
+    catch (error) {
+        throw new Error(`CODEX_LIFECYCLE_TASK_BINDING_MISMATCH: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    const binding = record.taskBinding;
+    if (!binding)
+        throw new Error('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH: lifecycle record has no receipt binding');
+    const repoRoot = options.repoRoot ?? options.orchestrationOptions?.repoRoot ?? process.cwd();
+    const resolved = resolveTaskRef(binding.taskId, { repoRoot });
+    if (!resolved.ok)
+        throw new Error(`${resolved.code}: ${resolved.message}`);
+    const run = readRun(resolved.taskDir);
+    const nativeAgent = record.state.startEvidence?.nativeAgent ?? record.state.spawn?.nativeAgent ?? '';
+    if (!taskRunMatchesReceipt(run, binding, nativeAgent)) {
+        throw new Error('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH: lifecycle record does not match the current pending task receipt');
+    }
+    const receipt = run.pendingDelegation;
+    return { store, record, binding, resolved, run, receipt };
+}
+function sameTaskReceipt(left, right) {
+    return left.runId === right.runId && left.id === right.id;
+}
+function sameLifecycleRevision(left, right) {
+    return left.revision === right.revision
+        && sameTaskBinding(left.taskBinding, right.taskBinding);
+}
+function sameTaskBinding(left, right) {
+    return left?.runId === right?.runId
+        && left?.receiptId === right?.receiptId;
+}
+function isBindingFailure(message) {
+    return /CODEX_LIFECYCLE_TASK_BINDING_MISMATCH|CODEX_EVIDENCE_(?:IDENTITY_MISMATCH|PARENT_MISMATCH|REPLAY_CONFLICT)|task binding|identity mismatch|ambiguous active children/iu.test(message);
+}
+function codexSealFailure(error, options, source) {
+    if (error instanceof OrchestrationStateError)
+        return bridgeFailure(error.code, error.message);
+    const message = error instanceof Error ? error.message : String(error);
+    if (message === 'CODEX_TURN_NOT_TERMINAL') {
+        return source === 'parent'
+            ? bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'The matching Codex child has not completed')
+            : pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', message, options);
+    }
+    if (isBindingFailure(message))
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', message);
+    return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', message, options);
+}
+function sameBoundLifecycleRecord(bound, current) {
+    return sameTaskReceipt(bound.receipt, current.receipt)
+        && sameLifecycleRevision(bound.record, current.record);
+}
+function candidateActivationState(state, events) {
+    return events.reduce((current, event) => reduceCodexLifecycleEvent(current, event), state);
+}
+function candidateActivationFailure(state, options) {
+    if (state.status === 'invalid') {
+        return bridgeFailure(state.error?.code ?? 'CODEX_EVIDENCE_IDENTITY_MISMATCH', state.error?.message ?? 'Codex lifecycle identity does not match');
+    }
+    if (state.status !== 'start-ready' || !state.startEvidence) {
+        return pauseBridge('ORCHESTRATION_CODEX_START_EVIDENCE_INVALID', 'Codex lifecycle start evidence is not ready', options);
+    }
+    return null;
+}
+async function collectActivationEvidence(childThreadId, options, bound) {
+    const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+    const current = recordMatchesTaskReceipt(childThreadId, options);
+    if (!sameBoundLifecycleRecord(bound, current)) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'task receipt or lifecycle revision changed while resolving Codex child evidence');
+    }
+    const candidateEvents = [resolved.resolution.thread, ...resolved.reroutes, resolved.resolution.settings];
+    const candidateState = candidateActivationState(bound.record.state, candidateEvents);
+    const candidateFailure = candidateActivationFailure(candidateState, options);
+    if (candidateFailure)
+        return candidateFailure;
+    const evidence = candidateState.startEvidence;
+    const repoRoot = options.repoRoot ?? process.cwd();
+    const preflight = await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot, {
+        sessionId: evidence.parentThreadId,
+        turnId: evidence.parentTurnId,
+        toolUseId: evidence.spawnToolUseId
+    });
+    const afterPreflight = recordMatchesTaskReceipt(childThreadId, options);
+    if (!sameBoundLifecycleRecord(bound, afterPreflight)) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'task receipt or lifecycle revision changed while validating Codex host evidence');
+    }
+    return { preflight, events: candidateEvents, evidence };
+}
+function applyCollectedActivationEvidence(childThreadId, options, store, bound, events) {
+    const current = recordMatchesTaskReceipt(childThreadId, options);
+    if (!sameBoundLifecycleRecord(bound, current)) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'task receipt or lifecycle revision changed before Codex activation');
+    }
+    for (const event of events)
+        store.apply(event);
+    const record = store.read(childThreadId);
+    return record.state.status === 'start-ready' && record.state.startEvidence
+        ? record
+        : bridgeFailure('CODEX_EVIDENCE_IDENTITY_MISMATCH', 'Codex lifecycle identity changed before activation');
+}
+function bridgeFailure(code, message) {
+    return {
+        status: 'failed', changed: false, taskId: null, run: null, next: null,
+        error: { code, message }
+    };
+}
+function pauseBridge(code, message, options) {
+    const paused = pauseMatchingOrchestrationDelegation('codex', code, message, coreOptions(options));
+    return paused.error?.code === 'ORCHESTRATION_DELEGATION_MISSING'
+        ? bridgeFailure(code, message)
+        : paused;
+}
+function requiredStore(options) {
+    if (!options.store)
+        throw new Error('Codex lifecycle store is required for orchestration bridge events');
+    return options.store;
+}
+async function prepareCodexOrchestrationDelegation(taskRef, input, options = {}) {
+    if (input.client !== 'codex')
+        return prepareOrchestrationDelegation(taskRef, input, coreOptions(options));
+    try {
+        const repoRoot = options.repoRoot ?? process.cwd();
+        const resolved = resolveTaskRef(taskRef, { repoRoot });
+        if (!resolved.ok)
+            return bridgeFailure(resolved.code, resolved.message);
+        await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot, undefined, resolved.taskId);
+        const prepared = prepareOrchestrationDelegation(taskRef, input, coreOptions(options));
+        const receipt = prepared.run?.pendingDelegation;
+        if (prepared.status !== 'running' || !receipt)
+            return prepared;
+        return Object.freeze({
+            ...prepared,
+            adapterContext: encodeCodexLifecycleBinding({
+                taskId: receipt.taskId,
+                runId: receipt.runId,
+                receiptId: receipt.id
+            })
+        });
+    }
+    catch (error) {
+        if (error instanceof OrchestrationStateError)
+            return bridgeFailure(error.code, error.message);
+        return bridgeFailure('ORCHESTRATION_CLIENT_PREFLIGHT_FAILED', error instanceof Error ? error.message : String(error));
+    }
+}
+async function activateCodexOrchestrationDelegation(childThreadId, options = {}) {
+    try {
+        const store = requiredStore(options);
+        const bound = recordMatchesTaskReceipt(childThreadId, options);
+        if (!['prepared', 'activated', 'stage-completed'].includes(bound.receipt.status)) {
+            return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'lifecycle task receipt is not in an activatable state');
+        }
+        if (!hasActivatableOrchestrationDelegation('codex', childThreadId, coreOptions(options))) {
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+        }
+        const activationEvidence = await collectActivationEvidence(childThreadId, options, bound);
+        if ('status' in activationEvidence)
+            return activationEvidence;
+        const { evidence, events, preflight } = activationEvidence;
+        const repoRoot = options.repoRoot ?? process.cwd();
+        const record = applyCollectedActivationEvidence(childThreadId, options, store, bound, events);
+        if ('status' in record)
+            return record;
+        const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
+        const storedAdapterEvidence = readDelegationAdapterEvidence(bound.receipt.taskId, bound.receipt.id, 'codex', coreOptions(options));
+        const adapterState = typeof storedAdapterEvidence === 'object' && storedAdapterEvidence !== null && !Array.isArray(storedAdapterEvidence)
+            ? storedAdapterEvidence
+            : {};
+        const activated = activateMatchingOrchestrationDelegation('codex', {
+            nativeAgent: evidence.nativeAgent,
+            childId: evidence.childThreadId,
+            parentId: evidence.parentThreadId,
+            spawnMode: evidence.spawnMode,
+            actualModel: evidence.actualModel.value,
+            actualReasoningEffort: evidence.actualReasoningEffort.value,
+            ...(evidence.modelFallbackReason ? { modelFallbackReason: evidence.modelFallbackReason } : {}),
+            ...(evidence.reasoningEffortFallbackReason
+                ? { reasoningEffortFallbackReason: evidence.reasoningEffortFallbackReason }
+                : {}),
+            clientEvidence: {
+                ...adapterState,
+                activationEvidence: {
+                    kind: 'codex-lifecycle-v2',
+                    hookDefinitionHash: evidence.hookDefinitionHash,
+                    startRevision: record.revision,
+                    ...buildIdentity,
+                    ...preflight.hookProvenance,
+                    capabilitySessionId: evidence.parentThreadId,
+                    capabilityTurnId: evidence.parentTurnId,
+                    spawnToolUseId: evidence.spawnToolUseId,
+                    spawnObservedAt: record.spawnObservedAt ?? undefined,
+                    controllerInstanceDigest: null,
+                    controlGeneration: null
+                }
+            }
+        }, coreOptions(options));
+        return activated;
+    }
+    catch (error) {
+        if (error instanceof OrchestrationStateError)
+            return bridgeFailure(error.code, error.message);
+        const message = error instanceof Error ? error.message : String(error);
+        if (isBindingFailure(message)) {
+            return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', message);
+        }
+        return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', message, options);
+    }
+}
+function matchingSpawnRecords(store, binding, spawn) {
+    return store.findByTaskBinding(binding).filter((record) => record.state.spawn?.sessionId === spawn.sessionId
+        && record.state.spawn?.turnId === spawn.turnId
+        && record.state.spawn?.toolUseId === spawn.toolUseId
+        && record.state.spawn?.nativeAgent === spawn.nativeAgent);
+}
+function verifySpawnTask(binding, spawn, store, options) {
+    const resolved = resolveTaskRef(binding.taskId, { repoRoot: options.repoRoot ?? process.cwd() });
+    if (!resolved.ok)
+        return bridgeFailure(resolved.code, resolved.message);
+    const run = readRun(resolved.taskDir);
+    if (!run)
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'Codex task has no current orchestration run');
+    verifyCodexLifecycleTaskBinding(binding, run, spawn.nativeAgent, {
+        requestedModel: spawn.requestedModel,
+        requestedReasoningEffort: spawn.requestedReasoningEffort
+    });
+    return { taskDir: resolved.taskDir };
+}
+async function resolveCurrentSpawnChild(childThreadId, spawn, options) {
+    const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+    if (resolved.resolution.thread.childThreadId !== childThreadId
+        || resolved.resolution.thread.parentThreadId !== spawn.sessionId
+        || resolved.resolution.thread.nativeAgent !== spawn.nativeAgent) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'resolved Codex child does not match the native spawn identity');
+    }
+    return { resolved };
+}
+async function activateCodexSpawnDelegation(spawn, options = {}) {
+    try {
+        const store = requiredStore(options);
+        const parsed = parseCodexLifecycleBinding(spawn.taskName);
+        if (!parsed)
+            return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISSING', 'Codex spawn task_name has no valid task binding');
+        const task = verifySpawnTask(parsed.binding, spawn, store, options);
+        if ('status' in task)
+            return task;
+        const candidates = matchingSpawnRecords(store, parsed.binding, spawn);
+        if (candidates.length !== 1) {
+            return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'Codex spawn does not identify one current task lifecycle record');
+        }
+        const childThreadId = resolveCodexSpawnedChild(spawn.transcriptPath, spawn);
+        const current = await resolveCurrentSpawnChild(childThreadId, spawn, options);
+        if ('status' in current)
+            return current;
+        const latestTask = verifySpawnTask(parsed.binding, spawn, store, options);
+        if ('status' in latestTask)
+            return latestTask;
+        const latestCandidates = matchingSpawnRecords(store, parsed.binding, spawn);
+        if (latestCandidates.length !== 1 || latestCandidates[0].revision !== candidates[0].revision) {
+            return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'Codex spawn record changed while resolving its child');
+        }
+        store.applyToSpawn({ ...spawn, taskBinding: parsed.binding }, {
+            type: 'hook-child',
+            sessionId: spawn.sessionId,
+            turnId: spawn.turnId,
+            childThreadId,
+            parentThreadId: current.resolved.resolution.thread.parentThreadId,
+            nativeAgent: spawn.nativeAgent,
+            source: 'parent-rollout'
+        }, latestCandidates[0].revision);
+        return activateCodexOrchestrationDelegation(childThreadId, {
+            ...options,
+            store,
+            resolveThread: async () => current.resolved
+        });
+    }
+    catch (error) {
+        if (error instanceof OrchestrationStateError)
+            return bridgeFailure(error.code, error.message);
+        const message = error instanceof Error ? error.message : String(error);
+        if (/CODEX_LIFECYCLE_TASK_BINDING_MISMATCH|task binding|task_name|identity does not match|does not match the current pending receipt|ambiguous/iu.test(message)) {
+            return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', message);
+        }
+        return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', message, options);
+    }
+}
+async function sealCodexOrchestrationDelegation(childThreadId, options = {}) {
+    try {
+        const bound = recordMatchesTaskReceipt(childThreadId, options);
+        if (!hasSealableOrchestrationDelegation('codex', childThreadId, coreOptions(options))) {
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+        }
+        const store = requiredStore(options);
+        const existing = store.read(childThreadId);
+        if (!existing.consumer) {
+            const stopTurnId = existing.state.stop?.turnId;
+            if (!stopTurnId) {
+                return pauseBridge('ORCHESTRATION_CODEX_STOP_EVIDENCE_INVALID', 'Codex lifecycle stop hook is not available', options);
+            }
+            const terminal = await (options.resolveTerminal ?? resolveCodexTerminal)(childThreadId, stopTurnId);
+            const current = recordMatchesTaskReceipt(childThreadId, options);
+            if (!sameTaskReceipt(bound.receipt, current.receipt) || !sameLifecycleRevision(existing, current.record)) {
+                return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'task receipt or lifecycle revision changed while resolving Codex terminal evidence');
+            }
+            store.apply(terminal);
+        }
+        const record = store.read(childThreadId);
+        const evidence = record.state.stopEvidence;
+        if (record.state.status !== 'stop-ready' || !evidence || !record.state.startEvidence) {
+            return pauseBridge('ORCHESTRATION_CODEX_STOP_EVIDENCE_INVALID', 'Codex lifecycle stop evidence is not ready', options);
+        }
+        const current = recordMatchesTaskReceipt(childThreadId, options);
+        const latest = store.read(childThreadId);
+        if (!sameTaskReceipt(bound.receipt, current.receipt) || !sameLifecycleRevision(record, latest)
+            || !sameTaskBinding(latest.taskBinding, current.binding)) {
+            throw new Error('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH: task receipt changed before lifecycle evidence consumption');
+        }
+        if (current.receipt.status === 'sealed') {
+            if (latest.consumer !== current.receipt.id || !latest.consumedAt) {
+                return pauseBridge('ORCHESTRATION_CODEX_RECONCILIATION_FAILED', 'Codex lifecycle evidence was not consumed by the sealed receipt', options);
+            }
+            return reconcileMatchingOrchestrationDelegation('codex', childThreadId, coreOptions(options));
+        }
+        return sealMatchingOrchestrationDelegation('codex', { nativeAgent: record.state.startEvidence.nativeAgent, childId: childThreadId }, coreOptions(options), () => {
+            try {
+                const consumed = store.consumeWithinTaskLock(childThreadId, current.receipt.id, existing.state.spawn?.hookDefinitionHash, existing.taskBinding ?? undefined);
+                return consumed.consumer === current.receipt.id && consumed.consumedAt
+                    ? null
+                    : bridgeFailure('ORCHESTRATION_CODEX_RECONCILIATION_FAILED', 'Codex lifecycle evidence was not consumed by the active receipt');
+            }
+            catch (error) {
+                return codexSealFailure(error, options, 'child');
+            }
+        });
+    }
+    catch (error) {
+        return codexSealFailure(error, options, 'child');
+    }
+}
+function findCurrentParentReceipt(store, repoRoot) {
+    if (!store.taskId)
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISSING', 'parent seal requires a task-scoped lifecycle store');
+    const resolved = resolveTaskRef(store.taskId, { repoRoot });
+    if (!resolved.ok)
+        return bridgeFailure(resolved.code, resolved.message);
+    const pending = readRun(resolved.taskDir)?.pendingDelegation;
+    if (!pending || pending.client !== 'codex') {
+        return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    }
+    return { pending };
+}
+function findParentLifecycleRecord(parentThreadId, store, pending) {
+    const binding = { taskId: pending.taskId, runId: pending.runId, receiptId: pending.id };
+    const candidates = store.findByTaskBinding(binding).filter((record) => record.state.startEvidence?.parentThreadId === parentThreadId);
+    if (!candidates.length)
+        return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+    if (candidates.length !== 1) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'parent seal has multiple lifecycle records for the current task receipt');
+    }
+    const active = candidates[0];
+    const start = active.state.startEvidence;
+    const child = active.state.child;
+    if (!start || !child || start.childThreadId !== child.childThreadId
+        || start.parentThreadId !== parentThreadId
+        || active.state.spawn?.sessionId !== parentThreadId
+        || active.state.spawn.nativeAgent !== start.nativeAgent
+        || managedDelegationRole(start.nativeAgent) !== pending.role) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'parent lifecycle record does not match the current native delegation identity');
+    }
+    return { active, start, child };
+}
+async function collectParentTerminalIfNeeded(active, start, options) {
+    if (active.state.terminal)
+        return null;
+    const resolveTerminal = options.resolveTerminal ?? resolveCodexTerminal;
+    return active.state.stop
+        ? resolveTerminal(start.childThreadId, active.state.stop.turnId)
+        : resolveTerminal(start.childThreadId);
+}
+function applyParentTerminalCandidate(parentThreadId, repoRoot, store, pending, active, start, child, terminal) {
+    const latestReceipt = findCurrentParentReceipt(store, repoRoot);
+    if ('status' in latestReceipt)
+        return latestReceipt;
+    if (!sameTaskReceipt(pending, latestReceipt.pending)) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'task receipt changed while resolving parent terminal evidence');
+    }
+    const latestMatch = findParentLifecycleRecord(parentThreadId, store, latestReceipt.pending);
+    if ('status' in latestMatch)
+        return latestMatch;
+    if (!sameLifecycleRevision(active, latestMatch.active)
+        || !sameTaskBinding(active.taskBinding, latestMatch.active.taskBinding)) {
+        return bridgeFailure('CODEX_LIFECYCLE_TASK_BINDING_MISMATCH', 'task receipt or lifecycle revision changed while resolving parent terminal evidence');
+    }
+    if (terminal)
+        store.apply(terminal);
+    if (!store.read(start.childThreadId).state.stop) {
+        store.apply({
+            type: 'hook-stop', sessionId: parentThreadId, turnId: child.turnId,
+            childThreadId: start.childThreadId, nativeAgent: start.nativeAgent, source: 'parent-rollout'
+        });
+    }
+    return null;
+}
+async function sealCodexParentDelegation(parentThreadId, options = {}) {
+    try {
+        const store = requiredStore(options);
+        const repoRoot = options.repoRoot ?? options.orchestrationOptions?.repoRoot ?? process.cwd();
+        const current = findCurrentParentReceipt(store, repoRoot);
+        if ('status' in current)
+            return current;
+        const pending = current.pending;
+        const match = findParentLifecycleRecord(parentThreadId, store, pending);
+        if ('status' in match)
+            return match;
+        const { active, start, child } = match;
+        if (active.consumer)
+            return sealCodexOrchestrationDelegation(start.childThreadId, options);
+        const terminal = await collectParentTerminalIfNeeded(active, start, options);
+        const failure = applyParentTerminalCandidate(parentThreadId, repoRoot, store, pending, active, start, child, terminal);
+        if (failure)
+            return failure;
+        return sealCodexOrchestrationDelegation(start.childThreadId, options);
+    }
+    catch (error) {
+        return codexSealFailure(error, options, 'parent');
+    }
+}
+function reconcileCodexOrchestrationDelegation(childThreadId, options = {}) {
+    try {
+        const bound = recordMatchesTaskReceipt(childThreadId, options);
+        const record = requiredStore(options).read(childThreadId);
+        if (bound.receipt.status !== 'sealed' || record.consumer !== bound.receipt.id || !record.consumedAt) {
+            return pauseBridge('ORCHESTRATION_CODEX_RECONCILIATION_FAILED', 'Codex lifecycle evidence was not consumed by the sealed receipt', options);
+        }
+    }
+    catch (error) {
+        return codexSealFailure(error, options, 'child');
+    }
+    return reconcileMatchingOrchestrationDelegation('codex', childThreadId, coreOptions(options));
+}
+export { activateCodexOrchestrationDelegation, activateCodexSpawnDelegation, prepareCodexOrchestrationDelegation, reconcileCodexOrchestrationDelegation, sealCodexParentDelegation, sealCodexOrchestrationDelegation };
+//# sourceMappingURL=codex-orchestration.js.map

package/dist/lib/agent-clients/adapters/codex.js

@@ -1,6 +1,41 @@
 import { defineAgentClientAdapter } from '../adapter.js';
 import { hostJoin } from '../../sandbox/engines/wsl2-paths.js';
 import { codexBeforeContainerCreateHook, codexRecoveryChecks } from './codex-sandbox.js';
+import { parseCodexLifecycleBinding } from './codex-lifecycle/binding.js';
+import { isCodexDelegationReceiptEvidence, isCodexLifecycleActivationEvidence } from './codex-lifecycle/evidence.js';
+import { codexControllerOperation } from './codex-lifecycle/controller-operation.js';
+function codexCarrierError(code) {
+    const error = new Error(code);
+    error.name = code;
+    return error;
+}
+function codexStageToken(stage) {
+    const tokens = {
+        analysis: 'a',
+        plan: 'p',
+        code: 'c',
+        'review-analysis': 'ra',
+        'review-plan': 'rp',
+        'review-code': 'rc',
+        commit: 'm'
+    };
+    const token = tokens[stage];
+    if (!token)
+        throw codexCarrierError('CODEX_LIFECYCLE_SPAWN_IDENTITY_INVALID');
+    return token;
+}
+function codexLaunchCarrier(adapterContext, identity) {
+    if (!Number.isSafeInteger(identity.round) || identity.round < 1
+        || !['executor', 'reviewer'].includes(identity.role)) {
+        throw codexCarrierError('CODEX_LIFECYCLE_SPAWN_IDENTITY_INVALID');
+    }
+    const label = `${codexStageToken(identity.stage)}_${identity.role === 'reviewer' ? 'r' : 'e'}_r${identity.round}`;
+    const taskName = `${label}${adapterContext}`;
+    const parsed = parseCodexLifecycleBinding(taskName);
+    if (!parsed)
+        throw codexCarrierError('CODEX_LIFECYCLE_LAUNCH_CONTEXT_INVALID');
+    return Object.freeze({ task_name: parsed.taskName });
+}
 const codexAdapter = defineAgentClientAdapter({
     id: 'codex',
     displayName: 'Codex',
@@ -25,8 +60,11 @@ const codexAdapter = defineAgentClientAdapter({
         actualReasoningEffort: 'app-server'
     },
     orchestrationAdapter: {
+        validateActivationEvidence: isCodexLifecycleActivationEvidence,
+        validateReceiptEvidence: isCodexDelegationReceiptEvidence,
+        createLaunchCarrier: codexLaunchCarrier,
         prepareDelegation: async (...args) => {
-            const { prepareCodexOrchestrationDelegation } = await import('../../task/codex-orchestration.js');
+            const { prepareCodexOrchestrationDelegation } = await import('./codex-orchestration.js');
             return prepareCodexOrchestrationDelegation(...args);
         },
         recoverStarted: async (...args) => {
@@ -34,6 +72,7 @@ const codexAdapter = defineAgentClientAdapter({
             return recoverStartedLifecycleFromAdapter(...args);
         }
     },
+    sandboxControlOperation: codexControllerOperation,
     project: {
         ownedPathPrefixes: ['.codex/'],
         managed: ['.codex/hooks.json', '.codex/agents/'],

package/dist/lib/agent-clients/adapters/index.js

@@ -1,22 +1,14 @@
-import { AGENT_CLIENT_IDS } from '../types.js';
 import { claudeCodeAdapter } from './claude-code.js';
 import { codexAdapter } from './codex.js';
 import { antigravityCliAdapter } from './antigravity-cli.js';
 import { opencodeAdapter } from './opencode.js';
 import { traecliAdapter } from './traecli.js';
-const adaptersById = new Map([
+const BUILTIN_AGENT_CLIENT_ADAPTERS = Object.freeze([
     claudeCodeAdapter,
     codexAdapter,
     antigravityCliAdapter,
     opencodeAdapter,
     traecliAdapter
-].map((adapter) => [adapter.id, adapter]));
-const BUILTIN_AGENT_CLIENT_ADAPTERS = Object.freeze(AGENT_CLIENT_IDS.map((id) => {
-    const adapter = adaptersById.get(id);
-    if (!adapter) {
-        throw new Error(`Missing built-in Agent Client adapter '${id}'`);
-    }
-    return adapter;
-}));
+]);
 export { BUILTIN_AGENT_CLIENT_ADAPTERS };
 //# sourceMappingURL=index.js.map

package/dist/lib/agent-clients/tokens.js

@@ -1,14 +1,15 @@
 // Active AI collaborator short tokens — the write-side whitelist for the
 // activity log. Migrated from lib/task/commands/log.ts so that the write-side
 // internal commands and the rendering side share one definition.
-export const KNOWN_AI_AGENTS = new Set(['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'traecli']);
+export const AGENT_TOKEN_VALUES = ['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'traecli'];
+export const KNOWN_AI_AGENTS = new Set(AGENT_TOKEN_VALUES);
 // Long name -> short name mapping: `claude-code` reuses the existing
 // orchestration precedent, and `antigravity-cli` is the active client.
 export const AGENT_LONG_NAMES = {
     'claude-code': 'claude',
     'antigravity-cli': 'antigravity'
 };
-export const AGENT_USAGE_HINT = "agent must be a short token (claude/codex/antigravity/opencode/cursor/traecli), " +
+export const AGENT_USAGE_HINT = `agent must be a short token (${AGENT_TOKEN_VALUES.join('/')}), ` +
     "a long name (claude-code -> claude, antigravity-cli -> antigravity), or 'human'";
 // Strict write-side validation: the value must be exactly a short token, a
 // long name, or 'human'; returns the normalized short token, or null when