@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/dist/lib/task/orchestration.js

@@ -7,14 +7,16 @@ 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, foldBlankToNull, managedDelegationRole, prepareDelegation, sealDelegation } from './delegation-receipts.js';
 import { normalizeAgentClients } from '../agent-clients/config.js';
+import { resolveAgentRuntimeStoreRoot } from '../runtime/agent-runtime.js';
 import { inspectPlatformPullRequest } from '../platform/pull-requests.js';
 import { getAgentClientCapability, getAgentClientDelegationEvidence, getAgentClientModelSelection } from '../agent-clients/registry.js';
 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 +35,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 +112,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)
@@ -175,6 +177,36 @@ function canRecoverCodexUnsupportedPause(run, taskDir) {
         && !fs.existsSync(commitIntentPath(taskDir))
         && (run.recoveryHistory ?? []).every((entry) => entry.code === 'MODEL_POLICY_SUPPLEMENTED');
 }
+function canRecoverClaudeCodeUnsupportedPause(run, taskDir) {
+    return run.schemaVersion === 3
+        && run.status === 'paused'
+        && run.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+        && run.modelPolicySource?.client === 'claude-code'
+        && 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 ?? []).length === 0;
+}
+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)
@@ -190,7 +222,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);
@@ -198,17 +230,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);
             }
@@ -221,6 +256,39 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
                 }
             }
             if (existing.status === 'paused' && existing.pause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED') {
+                if (existing.modelPolicySource.client === 'claude-code') {
+                    if (!canRecoverClaudeCodeUnsupportedPause(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_NO_MIGRATION',
+                        recoveredAt: now,
+                        previousSchemaVersion: 3,
+                        previousStatus: 'paused',
+                        previousPause,
+                        client: 'claude-code',
+                        guards: {
+                            stepCount: 0,
+                            nextStage: null,
+                            baselineEmpty: true,
+                            receiptCount: 0,
+                            pendingDelegation: false,
+                            commitAuthorizationUnused: true,
+                            completionEvidenceAbsent: true,
+                            commitIntentAbsent: true
+                        },
+                        resultingStatus: 'running'
+                    };
+                    const resumed = withUpdatedRun(existing, {
+                        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 (!canRecoverCodexUnsupportedPause(existing, resolved.taskDir)) {
                     return { status: 'paused', changed: false, taskId: resolved.taskId, run: existing, next: null, error: null };
                 }
@@ -246,6 +314,7 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
                     resultingStatus: 'running'
                 };
                 const resumed = withUpdatedRun(existing, {
+                    schemaVersion: 3,
                     status: 'running',
                     pause: null,
                     recoveryHistory: Object.freeze([...(existing.recoveryHistory ?? []), recovery])
@@ -254,7 +323,42 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
                 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 };
             }
@@ -328,7 +432,7 @@ function beginOrResumeOrchestration(taskRef, options = {}) {
         };
         const recovered = Object.freeze({
             ...existing,
-            schemaVersion: 2,
+            schemaVersion: 3,
             status: resultingStatus,
             modelPolicy: policy,
             modelPolicySource: source,
@@ -360,7 +464,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',
@@ -1025,6 +1129,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)
@@ -1045,6 +1152,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);
@@ -1074,8 +1184,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,
@@ -1099,6 +1210,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');
@@ -1108,7 +1252,7 @@ function matchingDelegations(predicate, options) {
         .filter((entry) => entry.isDirectory())
         .flatMap((entry) => {
         const run = readRun(path.join(activeRoot, entry.name));
-        if (run?.status !== 'running' || !run.pendingDelegation)
+        if (run?.schemaVersion !== 3 || run.status !== 'running' || !run.pendingDelegation)
             return [];
         const receipt = run.pendingDelegation;
         return predicate(receipt)
@@ -1124,6 +1268,15 @@ 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)
@@ -1137,9 +1290,9 @@ function activateMatchingOrchestrationDelegation(client, event, options = {}) {
             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.spawnMode ?? null) === (event.spawnMode ?? null)
+            && (receipt.actualModel ?? null) === foldBlankToNull(event.actualModel)
+            && (receipt.actualReasoningEffort ?? null) === foldBlankToNull(event.actualReasoningEffort)
             && receipt.modelFallbackReason === (event.modelFallbackReason ?? null)
             && receipt.reasoningEffortFallbackReason === (event.reasoningEffortFallbackReason ?? null)
             && receipt.hostEvidence?.hookDefinitionHash === event.hostEvidence?.hookDefinitionHash;
@@ -1184,7 +1337,11 @@ function sealMatchingOrchestrationDelegation(client, event, options = {}) {
             childId: event.childId,
             exitCode: 0,
             afterFingerprint,
-            changedPaths
+            changedPaths,
+            actualModel: event.actualModel,
+            actualReasoningEffort: event.actualReasoningEffort,
+            modelFallbackReason: event.modelFallbackReason,
+            reasoningEffortFallbackReason: event.reasoningEffortFallbackReason
         }, options);
     }
     catch (error) {
@@ -1217,7 +1374,7 @@ function sealMatchingOrchestrationDelegationWithHostEvidence(client, event, cons
         });
         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 });
+        const validated = sealDelegation(receipt, baseEvent, { now: options.now, requireHostEvidence: false });
         if (!validated.ok) {
             return pauseOrchestration(matched.taskId, validated.code, validated.message, true, options);
         }
@@ -1255,7 +1412,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 };
@@ -1265,6 +1430,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(resolveAgentRuntimeStoreRoot({ repoRoot: resolved.repoRoot, store: '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)
@@ -1272,6 +1539,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);
@@ -1294,6 +1563,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'
@@ -1338,6 +1609,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);
@@ -1352,6 +1625,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);
@@ -1380,5 +1655,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, pauseMatchingOrchestrationDelegation, pauseOrchestration, planOrchestrationStageCompletion, prepareOrchestrationDelegation, readRun, reconcileMatchingOrchestrationDelegation, recoverCommitIntent, routeOrchestration, sealMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence, 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/review-finalization.js

@@ -8,6 +8,7 @@ import { finalizeReviewSummaryContent } from './review-artifacts.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { validateLifecycleExecution } from './lifecycle-execution.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
+import { allowsManualOverride } from './guard-override.js';
 const STAGES = {
     analysis: { family: 'review-analysis', action: 'Review Analysis' },
     plan: { family: 'review-plan', action: 'Review Plan' },
@@ -60,7 +61,7 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)
         return failed(request, resolved.code, resolved.message, resolved.taskId);
-    if (resolved.state !== 'active') {
+    if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
         return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
     }
     const parsedArtifact = parseArtifactName(request.artifact);
@@ -168,7 +169,7 @@ function finalizeReviewSummaryUnlocked(request, options = {}) {
     };
 }
 function finalizeReviewSummary(request, options = {}) {
-    if (request.dryRun)
+    if (request.dryRun || options.lockAlreadyHeld)
         return finalizeReviewSummaryUnlocked(request, options);
     const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
     if (!resolved.ok)

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,