@fitlab-ai/agent-infra 0.9.5 → 0.9.7

package/dist/lib/task/orchestration.js

@@ -7,7 +7,7 @@ import { parseReviewSummary } from './review-artifacts.js';
 import { inspectArtifactDirectory } from './artifact-lifecycle.js';
 import { parseLedger, summarizeLedgerStage, validateLedgerRows } from './ledger.js';
 import { resolveTaskRef } from './resolve-ref.js';
-import { activateDelegation, completeDelegationStage, consumeDelegation, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
+import { activateDelegation, abortPreparedDelegation, completeDelegationStage, consumeDelegation, dispatchDelegation, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
 import { normalizeAgentClients } from '../agent-clients/config.js';
 import { inspectPlatformPullRequest } from '../platform/pull-requests.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
@@ -15,6 +15,7 @@ import { isAgentClientId } from '../agent-clients/types.js';
 import { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots } from './workspace-snapshot.js';
 import { assertGitRepositoryBinding } from '../git/worktree-identity.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { hasActiveCodexLifecycleEvidence } from '../agent-clients/adapters/codex-lifecycle/store.js';
 import { CommitIntentError, commitIntentPath, createCommitIntent, digest, readCommitIntent, removeCommitIntent, removeCommitIntentByDigest, serialize, updateCommitIntent } from './commit-intent.js';
 import { inspectCommitFinalization, planCommitTaskFinalization } from './commit-finalization.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
@@ -33,7 +34,7 @@ function readRun(taskDir) {
     if (!fs.existsSync(file))
         return null;
     const run = JSON.parse(fs.readFileSync(file, 'utf8'));
-    if (run.schemaVersion !== 2 || !isV2Policy(run.modelPolicy))
+    if (![2, 3].includes(run.schemaVersion) || !isV2Policy(run.modelPolicy))
         return run;
     return {
         ...run,
@@ -110,7 +111,7 @@ function commitFinalizationView(inspection) {
 }
 function validCommitRun(run, taskId) {
     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)
@@ -159,6 +160,36 @@ function resolveProjectPolicy(repoRoot, client) {
     const raw = JSON.parse(fs.readFileSync(configPath, 'utf8'));
     return normalizeAgentClients(raw).state[client].orchestration;
 }
+function canRecoverCodexUnsupportedPause(run, taskDir) {
+    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, taskDir) {
+    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, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -174,7 +205,7 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
         return failed('ORCHESTRATION_STATE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
     if (existing) {
-        if (![1, 2].includes(existing.schemaVersion)
+        if (![1, 2, 3].includes(existing.schemaVersion)
             || !Array.isArray(existing.receipts)
             || !Object.prototype.hasOwnProperty.call(existing, 'pendingDelegation')) {
             return failed('ORCHESTRATION_STATE_INVALID', 'orchestration state has an invalid schema', resolved.taskId);
@@ -182,17 +213,20 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
         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
                 || !existing.modelPolicySource
                 || !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);
             }
@@ -204,8 +238,77 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
                     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;
+                const recovery = {
+                    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 = 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 };
             }
@@ -279,7 +382,7 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
         };
         const recovered = Object.freeze({
             ...existing,
-            schemaVersion: 2,
+            schemaVersion: 3,
             status: resultingStatus,
             modelPolicy: policy,
             modelPolicySource: source,
@@ -311,7 +414,7 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
     const now = (options.now ?? (() => new Date().toISOString()))();
     const source = { kind: sourceKind, client: options.client, resolvedAt: now };
     const run = {
-        schemaVersion: 2,
+        schemaVersion: 3,
         taskId: resolved.taskId,
         runId: (options.id ?? randomUUID)(),
         status: 'running',
@@ -976,6 +1079,9 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     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)
@@ -996,6 +1102,9 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
     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);
@@ -1025,8 +1134,9 @@ function prepareOrchestrationDelegationUnlocked(taskRef, input, options = {}) {
         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,
@@ -1050,6 +1160,39 @@ function prepareOrchestrationDelegation(taskRef, input, options = {}) {
         throw error;
     }
 }
+function dispatchOrchestrationDelegationUnlocked(taskRef, options = {}) {
+    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, options = {}) {
+    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, options) {
     const repoRoot = options.repoRoot ?? process.cwd();
     const activeRoot = path.join(repoRoot, '.agents', 'workspace', 'active');
@@ -1059,7 +1202,7 @@ function matchingDelegations(predicate, options) {
         .filter((entry) => entry.isDirectory())
         .flatMap((entry) => {
         const run = readRun(path.join(activeRoot, entry.name));
-        if (!run?.pendingDelegation)
+        if (run?.schemaVersion !== 3 || run.status !== 'running' || !run.pendingDelegation)
             return [];
         const receipt = run.pendingDelegation;
         return predicate(receipt)
@@ -1075,18 +1218,50 @@ function uniqueMatchingDelegation(client, predicate, options) {
         return failed('ORCHESTRATION_DELEGATION_AMBIGUOUS', 'multiple lifecycle delegations match the native hook event');
     return matches[0];
 }
+function hasActivatableOrchestrationDelegation(client, childId, options = {}) {
+    return matchingDelegations((receipt) => receipt.client === client && (receipt.status === 'prepared'
+        || (receipt.childId === childId && ['activated', 'stage-completed'].includes(receipt.status))), options).length > 0;
+}
+function hasSealableOrchestrationDelegation(client, childId, options = {}) {
+    return matchingDelegations((receipt) => receipt.client === client
+        && receipt.childId === childId
+        && ['stage-completed', 'sealed'].includes(receipt.status), options).length > 0;
+}
 function activateMatchingOrchestrationDelegation(client, event, options = {}) {
     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 === '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, code, message, options = {}) {
+    const matched = uniqueMatchingDelegation(client, () => true, options);
+    if ('status' in matched)
+        return matched;
+    return pauseOrchestration(matched.taskId, code, message, true, options);
+}
 function sealMatchingOrchestrationDelegation(client, event, options = {}) {
     const role = managedDelegationRole(event.nativeAgent);
     if (!role)
@@ -1119,6 +1294,63 @@ function sealMatchingOrchestrationDelegation(client, event, options = {}) {
         return pauseOrchestration(matched.taskId, 'ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), true, options);
     }
 }
+function sealMatchingOrchestrationDelegationWithHostEvidence(client, event, consumeEvidence, options = {}) {
+    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, childId, options = {}) {
+    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, event, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -1126,7 +1358,15 @@ function activateOrchestrationDelegation(taskRef, event, options = {}) {
     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 };
@@ -1136,6 +1376,108 @@ function activateOrchestrationDelegation(taskRef, event, options = {}) {
     saveRun(resolved.taskDir, updated);
     return { status: 'running', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
+async function awaitOrchestrationDelegationActivation(taskRef, event, options = {}) {
+    const sleep = options.sleep
+        ?? ((milliseconds) => new Promise((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, options = {}) {
+    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, event, options = {}) {
     const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
@@ -1143,6 +1485,8 @@ function completeOrchestrationStage(taskRef, event, options = {}) {
     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);
@@ -1165,6 +1509,8 @@ function inspectOrchestrationStage(taskRef, event, options = {}) {
     }
     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
         || receipt.status !== 'activated'
@@ -1209,6 +1555,8 @@ function sealOrchestrationDelegation(taskRef, event, options = {}) {
     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);
@@ -1223,6 +1571,8 @@ function advanceOrchestration(taskRef, options = {}) {
     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);
@@ -1251,5 +1601,5 @@ function pauseOrchestration(taskRef, code, message, recoverable, options = {}) {
     saveRun(resolved.taskDir, updated);
     return { status: 'paused', changed: true, taskId: resolved.taskId, run: updated, next: null, error: null };
 }
-export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, advanceOrchestration, abortCommitIntent, beginCommitIntent, beginOrResumeOrchestration, checkpointCommitIntent, commitOrchestrationStageCompletion, completeCommitIntent, completeOrchestrationStage, inspectOrchestrationStage, orchestrationPath, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, recoverCommitIntent, routeOrchestration, sealMatchingOrchestrationDelegation, sealOrchestrationDelegation, startCommitAttempt, statusCommitIntent, statusOrchestration, terminateCommitAttempt };
+export { activateMatchingOrchestrationDelegation, activateOrchestrationDelegation, awaitOrchestrationDelegationActivation, advanceOrchestration, abortCommitIntent, beginCommitIntent, beginOrResumeOrchestration, checkpointCommitIntent, commitOrchestrationStageCompletion, completeCommitIntent, completeOrchestrationStage, dispatchOrchestrationDelegation, inspectOrchestrationStage, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, orchestrationPath, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverCommitIntent, recoverPreparedOrchestrationDelegation, routeOrchestration, sealMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence, sealOrchestrationDelegation, startCommitAttempt, statusCommitIntent, statusOrchestration, terminateCommitAttempt };
 //# sourceMappingURL=orchestration.js.map

package/dist/lib/task/sections.js

@@ -16,6 +16,10 @@ function parseTable(content, input) {
         new Set(input.columns).size !== input.columns.length) {
         throw new DocumentMutationError('MUTATION_INVALID', 'table columns are invalid');
     }
+    const keyColumn = input.keyColumn ?? input.columns[0];
+    if (!input.columns.includes(keyColumn)) {
+        throw new DocumentMutationError('MUTATION_INVALID', 'table key column is invalid');
+    }
     const sections = matchingSections(content, input.sectionAliases);
     if (sections.length === 0)
         return null;
@@ -60,7 +64,7 @@ function parseTable(content, input) {
             column,
             decodeCell(parsed.cells[columnIndex]).trim()
         ]));
-        const key = values[input.columns[0]];
+        const key = values[keyColumn];
         if (seen.has(key)) {
             throw new DocumentMutationError('TABLE_DUPLICATE_KEY', `duplicate table key '${key}'`);
         }

package/dist/lib/task/task-execution-lock.js

@@ -38,11 +38,12 @@ function parseOwner(raw, key) {
     try {
         const value = JSON.parse(raw);
         if (value !== null
-            && value.version === 1
+            && value.version === 2
             && Number.isSafeInteger(value.pid)
             && (value.pid ?? 0) > 0
-            && typeof value.startTime === 'string'
-            && value.startTime.length > 0
+            && typeof value.startTime === 'number'
+            && Number.isSafeInteger(value.startTime)
+            && value.startTime >= 0
             && typeof value.token === 'string'
             && value.token.length > 0
             && typeof value.owner === 'string'
@@ -148,7 +149,7 @@ function withTaskExecutionLock(repoRoot, taskId, ownerName, callback, options =
         throw new TaskExecutionLockError('ORCHESTRATION_LOCK_FAILED', 'current process start time is unavailable', { operation: 'identity', errno: null, key });
     }
     const owner = {
-        version: 1,
+        version: 2,
         pid: process.pid,
         startTime,
         token,