codex-orchestrator 2.0.10 → 2.0.11

package/dist/src/v2/run-store.js

@@ -1,10 +1,15 @@
-import { validateDirectReview } from './direct-delivery.js';
+import { validateDurableMutableInvocation, validateDurableReportInvocation, } from './contained-report-operation.js';
+import { projectTerminalDirectReview, validateDirectReview } from './direct-delivery.js';
 import { validateSpecDelivery } from './spec-delivery.js';
 import { validateRouteExecution, validateRouteReceipt, validateRouteStateInvariant, } from './route-decision.js';
 import { validateWaitingHumanExecution } from './waiting-human.js';
 import { posix } from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { AtomicStateFile } from './atomic-store.js';
-import { createReviewFeedbackBootstrap, validateImplementationInvocation, validateReviewFeedbackExecution, } from './review-feedback.js';
+import { writeDurableAtomicFile } from './adapters/durable-atomic-file.js';
+import { canonicalJson, sha256 } from './containment.js';
+import { validateCandidateBinding, validateCandidateExecutionLease } from './candidate.js';
+import { blockReviewFeedback, createReviewFeedbackBootstrap, validateReviewFeedbackExecution, } from './review-feedback.js';
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
 const GIT_SHA_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -22,15 +27,132 @@ export class RouteInitializationUnrecoverableError extends Error {
 }
 export class FileRunRecordWriter {
     file;
+    backupPath;
+    migrationMetadataPath;
+    reportLifecycleBackupPath;
+    mutableLifecycleBackupPath;
+    now;
     constructor(path, options = {}) {
         this.file = new AtomicStateFile(path, validateRunStateFile, options);
+        this.backupPath = `${path}.pre-candidate-v3`;
+        this.migrationMetadataPath = `${this.backupPath}.metadata.json`;
+        this.reportLifecycleBackupPath = `${path}.pre-report-lifecycle-v1`;
+        this.mutableLifecycleBackupPath = `${path}.pre-mutable-lifecycle-v1`;
+        this.now = options.now ?? (() => new Date().toISOString());
     }
     async read() {
-        return await this.file.read() ?? emptyRunState();
+        try {
+            return await this.file.read() ?? emptyRunState();
+        }
+        catch (error) {
+            return this.migrateLegacyReportLifecycle(error);
+        }
     }
     async compareAndSwap(expectedGeneration, next) {
         validateRunStateBody(next);
-        return this.file.compareAndSwap(expectedGeneration, { ...structuredClone(next), generation: expectedGeneration + 1 });
+        const candidate = { ...structuredClone(next), generation: expectedGeneration + 1 };
+        return this.file.compareAndSwapWithRaw(expectedGeneration, candidate, async (priorBytes) => {
+            if (!priorBytes)
+                return;
+            const raw = parseRawState(priorBytes);
+            if (raw.version === 3 && next.version !== 3)
+                throw new Error('run state V3 downgrade requires explicit rollback');
+            if (raw.version === 2 && next.version === 3)
+                await this.ensureCandidateMigrationBackup(priorBytes, raw.generation);
+        });
+    }
+    async markPublicationEffectPossible() {
+        await this.file.withExclusiveRaw(async () => {
+            const existing = await readMigrationMetadata(this.migrationMetadataPath);
+            if (!existing?.publicationEffectPossible) {
+                const now = this.now();
+                await writeDurableAtomicFile(this.migrationMetadataPath, `${canonicalJson({
+                    version: 1,
+                    sourceGeneration: existing?.sourceGeneration ?? null,
+                    sourceBytesSha256: existing?.sourceBytesSha256 ?? null,
+                    publicationEffectPossible: true,
+                    createdAt: existing?.createdAt ?? now,
+                    updatedAt: now,
+                })}\n`);
+            }
+            return { result: undefined };
+        });
+    }
+    async rollbackCandidateMigration(input) {
+        return this.file.withExclusiveRaw(async (_currentBytes, current) => {
+            const metadata = await readMigrationMetadata(this.migrationMetadataPath);
+            if (!metadata || metadata.sourceGeneration === null || metadata.sourceBytesSha256 === null)
+                throw new Error('candidate V3 rollback backup is unavailable');
+            if (metadata.publicationEffectPossible)
+                throw new Error('candidate V3 rollback is forbidden after publication boundary');
+            if (!current || current.version !== 3)
+                throw new Error('candidate V3 rollback requires active V3 state');
+            await input.assertNoActiveProcesses();
+            await input.cleanupCandidateState(structuredClone(current));
+            const backup = await readOptionalFile(this.backupPath);
+            if (!backup || sha256(backup) !== metadata.sourceBytesSha256)
+                throw new Error('candidate V3 rollback backup identity is invalid');
+            const restored = parseRawState(backup);
+            if (restored.version !== 2 || restored.generation !== metadata.sourceGeneration)
+                throw new Error('candidate V3 rollback backup generation is invalid');
+            return { result: restored, replacementBytes: backup };
+        });
+    }
+    async ensureCandidateMigrationBackup(rawV2Bytes, generation) {
+        const sourceBytesSha256 = sha256(rawV2Bytes);
+        const existing = await readMigrationMetadata(this.migrationMetadataPath);
+        const backup = await readOptionalFile(this.backupPath);
+        if (existing?.publicationEffectPossible)
+            throw new Error('candidate V3 migration backup cannot change after publication boundary');
+        if (existing?.sourceGeneration === generation && existing.sourceBytesSha256 === sourceBytesSha256
+            && backup?.equals(rawV2Bytes))
+            return;
+        await writeDurableAtomicFile(this.backupPath, rawV2Bytes);
+        const now = this.now();
+        await writeDurableAtomicFile(this.migrationMetadataPath, `${canonicalJson({
+            version: 1,
+            sourceGeneration: generation,
+            sourceBytesSha256,
+            publicationEffectPossible: false,
+            createdAt: now,
+            updatedAt: now,
+        })}\n`);
+    }
+    async migrateLegacyReportLifecycle(originalError) {
+        return this.file.withExclusiveUnparsedRaw(async (priorBytes) => {
+            if (!priorBytes)
+                return { result: emptyRunState() };
+            let raw;
+            try {
+                raw = JSON.parse(priorBytes.toString('utf8'));
+            }
+            catch {
+                throw originalError;
+            }
+            try {
+                return { result: validateRunStateFile(raw) };
+            }
+            catch {
+                const mutable = hasLegacyMutableLifecycle(raw);
+                let backupPath = mutable ? this.mutableLifecycleBackupPath : this.reportLifecycleBackupPath;
+                if (!mutable) {
+                    const priorReportBackup = await readOptionalFile(backupPath);
+                    if (priorReportBackup && !priorReportBackup.equals(priorBytes)) {
+                        const generation = raw.generation;
+                        backupPath = `${backupPath}.g${String(generation)}-${sha256(priorBytes).slice(0, 16)}`;
+                    }
+                }
+                const migrated = canonicalizeLegacyReportLifecycle(raw, backupPath);
+                if (!migrated)
+                    throw originalError;
+                const existingBackup = await readOptionalFile(backupPath);
+                if (existingBackup && !existingBackup.equals(priorBytes))
+                    throw new Error('report lifecycle migration backup conflicts with current source bytes');
+                if (!existingBackup)
+                    await writeDurableAtomicFile(backupPath, priorBytes);
+                return { result: migrated, replacementBytes: Buffer.from(`${canonicalJson(migrated)}\n`) };
+            }
+        });
     }
 }
 export class InMemoryRunRecordWriter {
@@ -41,14 +163,17 @@ export class InMemoryRunRecordWriter {
     async compareAndSwap(expectedGeneration, next) {
         if (this.state.generation !== expectedGeneration)
             throw new Error('run state generation conflict');
+        if (this.state.version === 3 && next.version !== 3)
+            throw new Error('run state V3 downgrade requires explicit rollback');
         const value = validateRunStateFile({ ...structuredClone(next), generation: expectedGeneration + 1 });
         this.state = value;
         return structuredClone(value);
     }
+    async markPublicationEffectPossible() { }
 }
 export function validateRunStateFile(value) {
     assertExactObject(value, ['schema', 'version', 'generation', 'runs'], 'run state');
-    if (value.schema !== 'codex-orchestrator.agent-auto-state' || (value.version !== 1 && value.version !== 2))
+    if (value.schema !== 'codex-orchestrator.agent-auto-state' || ![1, 2, 3].includes(value.version))
         throw new Error('run state schema/version is invalid');
     if (!Number.isSafeInteger(value.generation) || value.generation <= 0)
         throw new Error('run state generation is invalid');
@@ -67,13 +192,17 @@ export function validateRunStateFile(value) {
                 : structuredClone(run)),
         };
     }
+    if (value.version === 2)
+        assertNoCandidateV3Fields(value.runs);
     return value;
 }
 function validateRunStateBody(value) {
     assertExactObject(value, ['schema', 'version', 'runs'], 'run state body');
-    if (value.schema !== 'codex-orchestrator.agent-auto-state' || value.version !== 2)
+    if (value.schema !== 'codex-orchestrator.agent-auto-state' || (value.version !== 2 && value.version !== 3))
         throw new Error('run state schema/version is invalid');
     validateRuns(value.runs);
+    if (value.version === 2)
+        assertNoCandidateV3Fields(value.runs);
 }
 function validateRuns(value) {
     if (!Array.isArray(value) || value.length > 256)
@@ -88,7 +217,6 @@ function validateRuns(value) {
 }
 function validateRunRecord(value, field) {
     const optional = [
-        'process',
         'checkedChangeSha256',
         'proofId',
         'proofReceipt',
@@ -103,10 +231,15 @@ function validateRunRecord(value, field) {
         'reviewFeedback',
         'checkQualification',
         'baselineChecks',
+        'changeBindingVersion',
+        'candidateBinding',
+        'executionLease',
+        'reportInvocation',
+        'mutableInvocation',
     ].filter((key) => hasOwn(value, key));
     assertExactObject(value, [
         'runId', 'issueNumber', 'canonicalRepository', 'baseSha', 'branchName', 'worktreePath', 'lifecycle', 'cycle',
-        'reportRepairs', 'transportRetries', 'issueSnapshot', 'frozenCriteria', 'reworkFindings',
+        'reportRepairs', 'issueSnapshot', 'frozenCriteria', 'reworkFindings',
         'packageVersion', 'workflowGeneration', 'skillHashes', 'checks', 'createdAt', 'updatedAt', ...optional,
     ], field);
     if (typeof value.runId !== 'string' || !UUID_V4_PATTERN.test(value.runId))
@@ -126,8 +259,6 @@ function validateRunRecord(value, field) {
         throw new Error(`${field}.cycle is invalid`);
     if (value.reportRepairs !== 0 && value.reportRepairs !== 1)
         throw new Error(`${field}.reportRepairs is invalid`);
-    if (value.transportRetries !== 0 && value.transportRetries !== 1)
-        throw new Error(`${field}.transportRetries is invalid`);
     validateIssueSnapshot(value.issueSnapshot, `${field}.issueSnapshot`);
     validateFrozenCriteria(value.frozenCriteria, `${field}.frozenCriteria`);
     validateStringList(value.reworkFindings, `${field}.reworkFindings`);
@@ -146,8 +277,32 @@ function validateRunRecord(value, field) {
     if (hasOwn(value, 'baselineChecks'))
         validateChecks(value.baselineChecks, `${field}.baselineChecks`, false);
     validateChecks(value.checks, `${field}.checks`);
-    if (hasOwn(value, 'process'))
-        validateProcess(value.process, `${field}.process`);
+    let reportInvocation;
+    if (hasOwn(value, 'reportInvocation')) {
+        const invocation = validateDurableReportInvocation(value.reportInvocation);
+        reportInvocation = invocation;
+        const expectedLifecycle = invocation.operation === 'triage' || invocation.operation === 'ambiguity-review'
+            ? 'triaging'
+            : invocation.operation === 'code-review' ? 'implementing' : 'spec-authoring';
+        if (value.lifecycle !== expectedLifecycle)
+            throw new Error(`${field}.reportInvocation lifecycle is invalid`);
+    }
+    if (hasOwn(value, 'mutableInvocation')) {
+        const invocation = validateDurableMutableInvocation(value.mutableInvocation);
+        if (value.lifecycle !== 'implementing')
+            throw new Error(`${field}.mutableInvocation lifecycle is invalid`);
+        if (invocation.worktreePath !== value.worktreePath || invocation.generationHash !== routeGenerationHash) {
+            throw new Error(`${field}.mutableInvocation binding is invalid`);
+        }
+        if (invocation.operation === 'qualification-repair' && !hasOwn(value, 'checkQualification')) {
+            throw new Error(`${field}.qualification mutableInvocation requires check qualification`);
+        }
+        const feedbackActive = hasOwn(value, 'reviewFeedback')
+            && value.reviewFeedback.activeBatch !== null;
+        if ((invocation.operation === 'review-feedback-implementation') !== feedbackActive) {
+            throw new Error(`${field}.mutableInvocation feedback binding is invalid`);
+        }
+    }
     if (hasOwn(value, 'checkedChangeSha256'))
         assertSha256(value.checkedChangeSha256, `${field}.checkedChangeSha256`);
     if (hasOwn(value, 'proofId'))
@@ -175,24 +330,9 @@ function validateRunRecord(value, field) {
         if (!hasOwn(value, 'routeReceipt') || value.routeReceipt.route !== 'direct') {
             throw new Error(`${field}.directReview requires a direct route`);
         }
-        const rawProcess = hasOwn(value, 'process') && hasOwn(value.process, 'purpose')
-            ? value.process
-            : undefined;
-        const process = rawProcess && !['spec-author', 'spec-review'].includes(rawProcess.purpose)
-            ? {
-                purpose: rawProcess.purpose,
-                resumeLifecycle: rawProcess.resumeLifecycle,
-                resumeReviewStage: rawProcess.resumeReviewStage,
-            }
-            : undefined;
         validateDirectReview(value.directReview, {
             lifecycle: value.lifecycle,
             ...(hasOwn(value, 'terminalOutcome') ? { terminalOutcome: directTerminalOutcome(value.terminalOutcome) } : {}),
-            ...(process ? { process: {
-                    purpose: process.purpose,
-                    resumeLifecycle: process.resumeLifecycle,
-                    resumeReviewStage: process.resumeReviewStage,
-                } } : {}),
         });
     }
     if (hasOwn(value, 'specDelivery')) {
@@ -209,6 +349,31 @@ function validateRunRecord(value, field) {
         validateReviewFeedbackExecution(value.reviewFeedback);
         validateReviewFeedbackRunInvariant(value, field);
     }
+    if (hasOwn(value, 'changeBindingVersion') && value.changeBindingVersion !== 2)
+        throw new Error(`${field}.changeBindingVersion is invalid`);
+    if (hasOwn(value, 'candidateBinding'))
+        validateCandidateBinding(value.candidateBinding, `${field}.candidateBinding`, value.runId);
+    if (hasOwn(value, 'executionLease'))
+        validateCandidateExecutionLease(value.executionLease, `${field}.executionLease`);
+    if (hasOwn(value, 'candidateBinding') !== hasOwn(value, 'changeBindingVersion'))
+        throw new Error(`${field} candidate binding version is incomplete`);
+    if (hasOwn(value, 'executionLease')) {
+        if (!hasOwn(value, 'candidateBinding'))
+            throw new Error(`${field}.executionLease requires candidate binding`);
+        const binding = value.candidateBinding;
+        const lease = value.executionLease;
+        if (lease.bindingId !== binding.bindingId || lease.candidateCommitSha !== binding.candidateCommitSha)
+            throw new Error(`${field}.executionLease binding is invalid`);
+    }
+    if (hasOwn(value, 'intent') && hasOwn(value.intent, 'candidateRef')) {
+        if (!hasOwn(value, 'candidateBinding'))
+            throw new Error(`${field}.intent candidate ref requires candidate binding`);
+        const binding = value.candidateBinding;
+        const intent = value.intent;
+        if (intent.candidateRef !== binding.candidateRef || intent.treeSha !== binding.candidateTreeSha) {
+            throw new Error(`${field}.intent candidate binding is invalid`);
+        }
+    }
     if (hasOwn(value, 'checkQualification'))
         validateCheckQualification(value.checkQualification, `${field}.checkQualification`);
     assertTimestamp(value.createdAt, `${field}.createdAt`);
@@ -224,14 +389,16 @@ function validateRunRecord(value, field) {
     }
     if (value.lifecycle === 'publishing' && !hasOwn(value, 'proofReceipt'))
         throw new Error(`${field} publishing requires proofReceipt`);
-    if (value.lifecycle === 'safe-halt' && !hasOwn(value, 'process'))
-        throw new Error(`${field} safe-halt requires retained process evidence`);
     if (value.lifecycle === 'review-ready' && (!hasOwn(value, 'proofReceipt') || hasOwn(value, 'intent'))) {
         throw new Error(`${field} review-ready requires proofReceipt and no intent`);
     }
-    if (terminal && hasOwn(value, 'process'))
-        throw new Error(`${field} terminal lifecycle cannot retain process ownership`);
-    if (terminal && hasOwn(value, 'intent') && value.lifecycle !== 'transport-failed')
+    const retainedCandidateIntent = value.lifecycle === 'blocked'
+        && value.terminalOutcome?.status === 'blocked'
+        && value.terminalOutcome.kind === 'safety'
+        && !value.terminalOutcome.resumable
+        && hasOwn(value, 'candidateBinding')
+        && (value.intent?.kind === 'commit' || value.intent?.kind === 'review-update-commit');
+    if (terminal && hasOwn(value, 'intent') && value.lifecycle !== 'transport-failed' && !retainedCandidateIntent)
         throw new Error(`${field} terminal lifecycle cannot retain intent`);
     if (value.lifecycle === 'transport-failed' && hasOwn(value, 'intent')
         && value.terminalOutcome.resumable) {
@@ -239,6 +406,8 @@ function validateRunRecord(value, field) {
     }
     if (value.lifecycle === 'waiting-human' && !hasOwn(value, 'waitingHuman'))
         throw new Error(`${field} waiting-human lifecycle requires waitingHuman execution`);
+    if (reportInvocation)
+        validateReportInvocationBinding(value, reportInvocation, routeGenerationHash, field);
     validateRouteStateInvariant({
         lifecycle: value.lifecycle,
         routeExecution: value.routeExecution,
@@ -246,6 +415,39 @@ function validateRunRecord(value, field) {
         generationHash: routeGenerationHash,
     });
 }
+function validateReportInvocationBinding(record, invocation, generationHash, field) {
+    if (invocation.generationHash !== generationHash)
+        throw new Error(`${field}.reportInvocation generation is invalid`);
+    if (invocation.operation === 'triage') {
+        if (!record.routeExecution || !['triage-in-flight', 'repair-in-flight'].includes(record.routeExecution.phase)) {
+            throw new Error(`${field}.triage reportInvocation phase is invalid`);
+        }
+        return;
+    }
+    if (invocation.operation === 'ambiguity-review') {
+        if (record.routeExecution?.phase !== 'review-in-flight')
+            throw new Error(`${field}.ambiguity reportInvocation phase is invalid`);
+        return;
+    }
+    if (invocation.operation === 'code-review') {
+        if (record.directReview?.status !== 'active'
+            || !['review-full', 'review-closure'].includes(record.directReview.stage ?? '')
+            || record.executionLease?.operation !== 'direct-review') {
+            throw new Error(`${field}.code-review reportInvocation binding is invalid`);
+        }
+        return;
+    }
+    if (invocation.operation === 'spec-author') {
+        if (!record.specDelivery || !['authoring', 'author-repair'].includes(record.specDelivery.stage)
+            || record.specDelivery.authorSessionId === null) {
+            throw new Error(`${field}.spec-author reportInvocation binding is invalid`);
+        }
+        return;
+    }
+    if (!record.specDelivery || !['review-full', 'review-closure'].includes(record.specDelivery.stage)) {
+        throw new Error(`${field}.spec-review reportInvocation binding is invalid`);
+    }
+}
 function directTerminalOutcome(outcome) {
     if (outcome.status === 'review-ready')
         return undefined;
@@ -265,54 +467,36 @@ function validateWorkflowGeneration(value, field) {
     }
     assertSha256(value.contentSha256, `${field}.contentSha256`);
 }
-function validateProcess(value, field) {
-    assertExactObject(value, [
-        'pid', 'processGroupId', 'startedAt', 'baseline', 'purpose', 'resumeLifecycle', 'resumeReviewStage',
-    ], field);
-    assertPositiveInteger(value.pid, `${field}.pid`);
-    assertPositiveInteger(value.processGroupId, `${field}.processGroupId`);
-    assertTimestamp(value.startedAt, `${field}.startedAt`);
-    assertExactObject(value.baseline, [
-        'headSha', 'indexTreeSha', 'trackedContentSha256', 'untrackedContentSha256', 'worktreeIdentity',
-    ], `${field}.baseline`);
-    assertGitSha(value.baseline.headSha, `${field}.baseline.headSha`);
-    assertGitSha(value.baseline.indexTreeSha, `${field}.baseline.indexTreeSha`);
-    assertSha256(value.baseline.trackedContentSha256, `${field}.baseline.trackedContentSha256`);
-    assertSha256(value.baseline.untrackedContentSha256, `${field}.baseline.untrackedContentSha256`);
-    assertNonEmptyString(value.baseline.worktreeIdentity, `${field}.baseline.worktreeIdentity`);
-    if (!['route', 'implementation', 'code-review', 'proof', 'spec-author', 'spec-review'].includes(value.purpose)) {
-        throw new Error(`${field}.purpose is invalid`);
-    }
-    if (!isLifecycle(value.resumeLifecycle))
-        throw new Error(`${field}.resumeLifecycle is invalid`);
-    if (value.resumeReviewStage !== null && ![
-        'review-full', 'review-repair', 'review-closure',
-    ].includes(value.resumeReviewStage))
-        throw new Error(`${field}.resumeReviewStage is invalid`);
-}
 function validateChecks(value, field, allowUnchangedFailure = true) {
     if (!Array.isArray(value) || value.length > 256)
         throw new Error(`${field} is invalid`);
     const ids = new Set();
     for (const [index, check] of value.entries()) {
-        assertExactObject(check, ['id', 'command', 'status', 'outputSha256'], `${field}[${index}]`);
+        const candidate = hasOwn(check, 'bindingId') || hasOwn(check, 'candidateTreeSha') || hasOwn(check, 'checkPolicySha256');
+        assertExactObject(check, [
+            'id', 'command', 'status', 'outputSha256',
+            ...(candidate ? ['bindingId', 'candidateTreeSha', 'checkPolicySha256'] : []),
+        ], `${field}[${index}]`);
         assertNonEmptyString(check.id, `${field}[${index}].id`);
         assertNonEmptyString(check.command, `${field}[${index}].command`);
         if (check.status !== 'passed' && check.status !== 'failed'
             && (check.status !== 'unchanged-failure' || !allowUnchangedFailure))
             throw new Error(`${field}[${index}].status is invalid`);
         assertSha256(check.outputSha256, `${field}[${index}].outputSha256`);
+        if (candidate) {
+            assertSha256(check.bindingId, `${field}[${index}].bindingId`);
+            assertGitSha(check.candidateTreeSha, `${field}[${index}].candidateTreeSha`);
+            assertSha256(check.checkPolicySha256, `${field}[${index}].checkPolicySha256`);
+            if (check.status === 'unchanged-failure')
+                throw new Error(`${field}[${index}] candidate status is invalid`);
+        }
         if (ids.has(check.id))
             throw new Error(`${field} IDs must be unique`);
         ids.add(check.id);
     }
 }
 function validateCheckQualification(value, field) {
-    const optional = [
-        ...(hasOwn(value, 'implementationStarted') ? ['implementationStarted'] : []),
-        ...(hasOwn(value, 'repairInvocation') ? ['repairInvocation'] : []),
-        ...(hasOwn(value, 'deniedPathsBaseline') ? ['deniedPathsBaseline'] : []),
-    ];
+    const optional = hasOwn(value, 'repairFindings') ? ['repairFindings'] : [];
     assertExactObject(value, ['version', 'checkPolicySha256', 'repairAttempts', 'checks', ...optional], field);
     if (value.version !== 1)
         throw new Error(`${field}.version is invalid`);
@@ -321,26 +505,8 @@ function validateCheckQualification(value, field) {
         throw new Error(`${field}.repairAttempts is invalid`);
     }
     validateChecks(value.checks, `${field}.checks`, false);
-    if (hasOwn(value, 'implementationStarted') && typeof value.implementationStarted !== 'boolean') {
-        throw new Error(`${field}.implementationStarted is invalid`);
-    }
-    if (hasOwn(value, 'repairInvocation') && value.repairInvocation !== null) {
-        validateImplementationInvocation(value.repairInvocation);
-    }
-    if (hasOwn(value, 'deniedPathsBaseline'))
-        assertSha256(value.deniedPathsBaseline, `${field}.deniedPathsBaseline`);
-    if (hasOwn(value, 'deniedPathsBaseline') !== (hasOwn(value, 'repairInvocation') && value.repairInvocation !== null)) {
-        throw new Error(`${field}.deniedPathsBaseline requires a repair invocation`);
-    }
-    const repairInvocation = hasOwn(value, 'repairInvocation')
-        ? value.repairInvocation
-        : undefined;
-    if (value.implementationStarted === true && repairInvocation !== null && repairInvocation !== undefined) {
-        throw new Error(`${field} cannot own qualification repair and implementation launches together`);
-    }
-    if (repairInvocation?.phase === 'launched' && value.repairAttempts === 0) {
-        throw new Error(`${field}.repairAttempts must reserve a launched repair`);
-    }
+    if (hasOwn(value, 'repairFindings'))
+        validateStringList(value.repairFindings, `${field}.repairFindings`);
 }
 function validateIssueSnapshot(value, field) {
     const optional = hasOwn(value, 'comments') ? ['comments'] : [];
@@ -408,10 +574,12 @@ function validateIntent(value, field) {
         validateStringArray(value.expected, `${field}.expected`);
     }
     else if (kind === 'commit') {
-        assertExactObject(value, ['kind', 'parentSha', 'treeSha', 'message'], field);
+        assertExactObject(value, ['kind', 'parentSha', 'treeSha', 'message', ...(hasOwn(value, 'candidateRef') ? ['candidateRef'] : [])], field);
         assertGitSha(value.parentSha, `${field}.parentSha`);
         assertGitSha(value.treeSha, `${field}.treeSha`);
         assertNonEmptyString(value.message, `${field}.message`);
+        if (hasOwn(value, 'candidateRef'))
+            assertCandidateRef(value.candidateRef, `${field}.candidateRef`);
     }
     else if (kind === 'push') {
         assertExactObject(value, ['kind', 'branch', 'sha'], field);
@@ -437,11 +605,13 @@ function validateIntent(value, field) {
         validateStringArray(value.expected, `${field}.expected`);
     }
     else if (kind === 'review-update-commit') {
-        assertExactObject(value, ['kind', 'batchId', 'parentSha', 'treeSha', 'message'], field);
+        assertExactObject(value, ['kind', 'batchId', 'parentSha', 'treeSha', 'message', ...(hasOwn(value, 'candidateRef') ? ['candidateRef'] : [])], field);
         assertSha256(value.batchId, `${field}.batchId`);
         assertGitSha(value.parentSha, `${field}.parentSha`);
         assertGitSha(value.treeSha, `${field}.treeSha`);
         assertNonEmptyString(value.message, `${field}.message`);
+        if (hasOwn(value, 'candidateRef'))
+            assertCandidateRef(value.candidateRef, `${field}.candidateRef`);
     }
     else if (kind === 'review-update-push') {
         assertExactObject(value, ['kind', 'batchId', 'branch', 'priorRemoteSha', 'sha', 'treeSha'], field);
@@ -563,7 +733,213 @@ function validateStringArray(value, field) {
         throw new Error(`${field} must be sorted and unique`);
 }
 function emptyRunState() {
-    return { schema: 'codex-orchestrator.agent-auto-state', version: 2, generation: 0, runs: [] };
+    return { schema: 'codex-orchestrator.agent-auto-state', version: 3, generation: 0, runs: [] };
+}
+function canonicalizeLegacyReportLifecycle(value, backupPath) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (raw.schema !== 'codex-orchestrator.agent-auto-state' || (raw.version !== 2 && raw.version !== 3)
+        || !Number.isSafeInteger(raw.generation) || raw.generation <= 0 || !Array.isArray(raw.runs))
+        return undefined;
+    const runs = structuredClone(raw.runs);
+    const changed = runs.map((run) => canonicalizeLegacyReportRun(run, backupPath)).some(Boolean);
+    if (!changed)
+        return undefined;
+    return validateRunStateFile({ schema: raw.schema, version: raw.version, generation: raw.generation + 1, runs });
+}
+function canonicalizeLegacyReportRun(run, backupPath) {
+    let changed = false, unsafe = false, routeInFlight = false;
+    const mutable = canonicalizeLegacyMutableRun(run);
+    changed ||= mutable.changed;
+    unsafe ||= mutable.unsafe;
+    const route = run.routeExecution;
+    if (route) {
+        const triageTransport = hasOwn(route, 'triageTransportRetries'), ambiguityTransport = hasOwn(route, 'ambiguityTransportRetries');
+        if (triageTransport !== ambiguityTransport)
+            throw new Error('legacy route transport budgets are incomplete');
+        if (triageTransport) {
+            legacyBits([route.triageTransportRetries, route.ambiguityTransportRetries], 'route');
+            delete route.triageTransportRetries;
+            delete route.ambiguityTransportRetries;
+            changed = true;
+        }
+        if (hasOwn(route, 'previousAttemptId')) {
+            delete route.previousAttemptId;
+            changed = true;
+        }
+        routeInFlight = ['triage-in-flight', 'review-in-flight', 'repair-in-flight'].includes(route.phase);
+        if (routeInFlight) {
+            unsafe = true;
+            delete route.attemptId;
+            delete route.startedAt;
+        }
+    }
+    const direct = run.directReview;
+    if (direct?.review && hasOwn(direct.review, 'transportRetries')) {
+        legacyBits([direct.review.transportRetries], 'direct review');
+        delete direct.review.transportRetries;
+        changed = true;
+    }
+    if (direct && hasOwn(direct, 'invocation')) {
+        delete direct.invocation;
+        unsafe = changed = true;
+    }
+    const spec = run.specDelivery;
+    if (spec?.budgets?.author && hasOwn(spec.budgets.author, 'transportRetries')) {
+        legacyBits([spec.budgets.author.transportRetries], 'spec author');
+        delete spec.budgets.author.transportRetries;
+        changed = true;
+    }
+    if (spec?.budgets?.review && hasOwn(spec.budgets.review, 'transportRetries')) {
+        legacyBits([spec.budgets.review.transportRetries], 'spec review');
+        delete spec.budgets.review.transportRetries;
+        changed = true;
+    }
+    if (spec?.review && !hasOwn(spec.review, 'reviewerSessionId')) {
+        spec.review.reviewerSessionId = spec.review.reviewer?.sessionId ?? (spec.invocation?.purpose === 'review' ? spec.invocation.sessionId : null);
+        changed = true;
+    }
+    if (spec?.invocation?.purpose === 'review') {
+        delete spec.invocation;
+        unsafe = changed = true;
+    }
+    if (spec?.invocation?.purpose === 'author') {
+        if (spec.invocation.status === 'launched')
+            unsafe = true;
+        if (spec.authorSessionId === null)
+            spec.authorSessionId = spec.invocation.sessionId;
+        else if (spec.authorSessionId !== spec.invocation.sessionId)
+            unsafe = true;
+        delete spec.invocation;
+        changed = true;
+    }
+    if (run.reportInvocation && !hasOwn(run.reportInvocation, 'promptFactsSha256')) {
+        delete run.reportInvocation;
+        unsafe = changed = true;
+    }
+    if (run.process && ['route', 'code-review', 'spec-author', 'spec-review', 'proof'].includes(run.process.purpose)) {
+        delete run.process;
+        unsafe = changed = true;
+    }
+    if (!unsafe)
+        return changed;
+    if (routeInFlight)
+        delete run.routeExecution;
+    delete run.reportInvocation;
+    delete run.process;
+    delete run.intent;
+    if (direct)
+        run.directReview = projectTerminalDirectReview(direct, { status: 'blocked', kind: 'safety' }, 'report-lifecycle-migration-identity-unavailable');
+    run.lifecycle = 'blocked';
+    run.outcomeEvidenceId = `report-lifecycle-migration:${String(run.runId)}`;
+    run.terminalOutcome = { status: 'blocked', kind: 'safety', resumable: false, evidencePath: backupPath };
+    return true;
+}
+function hasLegacyMutableLifecycle(value) {
+    if (typeof value !== 'object' || value === null || !Array.isArray(value.runs))
+        return false;
+    return (value.runs).some((run) => hasOwn(run, 'transportRetries') || run.process?.purpose === 'implementation'
+        || hasOwn(run.checkQualification, 'implementationStarted') || hasOwn(run.checkQualification, 'repairInvocation')
+        || hasOwn(run.checkQualification, 'deniedPathsBaseline') || hasOwn(run.reviewFeedback, 'implementationInvocation'));
+}
+function canonicalizeLegacyMutableRun(run) {
+    let changed = false, unsafe = false;
+    if (hasOwn(run, 'transportRetries')) {
+        legacyBits([run.transportRetries], 'mutable invocation');
+        delete run.transportRetries;
+        changed = true;
+    }
+    const qualification = run.checkQualification;
+    if (qualification) {
+        if (qualification.repairInvocation?.phase === 'launched')
+            unsafe = true;
+        for (const field of ['implementationStarted', 'repairInvocation', 'deniedPathsBaseline'])
+            if (hasOwn(qualification, field)) {
+                delete qualification[field];
+                changed = true;
+            }
+    }
+    const feedback = run.reviewFeedback;
+    if (feedback && hasOwn(feedback, 'implementationInvocation')) {
+        if (feedback.implementationInvocation?.phase === 'launched')
+            unsafe = true;
+        delete feedback.implementationInvocation;
+        changed = true;
+    }
+    if (run.process?.purpose === 'implementation') {
+        delete run.process;
+        changed = unsafe = true;
+    }
+    if (!unsafe)
+        return { changed, unsafe };
+    delete run.mutableInvocation;
+    if (feedback?.activeBatch)
+        run.reviewFeedback = blockReviewFeedback(feedback, 'safety', String(run.updatedAt));
+    return { changed: true, unsafe: true };
+}
+function legacyBits(values, owner) {
+    if (values.some((value) => value !== 0 && value !== 1))
+        throw new Error(`legacy ${owner} transport budget is invalid`);
+}
+function parseRawState(bytes) {
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('run state JSON is malformed');
+    }
+    return validateRunStateFile(value);
+}
+async function readOptionalFile(path) {
+    try {
+        return await readFile(path);
+    }
+    catch (error) {
+        if (isErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+}
+async function readMigrationMetadata(path) {
+    const bytes = await readOptionalFile(path);
+    if (!bytes)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(bytes.toString('utf8'));
+    }
+    catch {
+        throw new Error('candidate migration metadata is malformed');
+    }
+    assertExactObject(value, [
+        'version', 'sourceGeneration', 'sourceBytesSha256', 'publicationEffectPossible', 'createdAt', 'updatedAt',
+    ], 'candidate migration metadata');
+    if (value.version !== 1)
+        throw new Error('candidate migration metadata version is invalid');
+    if (value.sourceGeneration !== null && (!Number.isSafeInteger(value.sourceGeneration) || value.sourceGeneration <= 0)) {
+        throw new Error('candidate migration source generation is invalid');
+    }
+    if (value.sourceBytesSha256 !== null)
+        assertSha256(value.sourceBytesSha256, 'candidate migration source hash');
+    if ((value.sourceGeneration === null) !== (value.sourceBytesSha256 === null))
+        throw new Error('candidate migration source identity is incomplete');
+    if (typeof value.publicationEffectPossible !== 'boolean')
+        throw new Error('candidate migration publication watermark is invalid');
+    assertTimestamp(value.createdAt, 'candidate migration createdAt');
+    assertTimestamp(value.updatedAt, 'candidate migration updatedAt');
+    return value;
+}
+function assertNoCandidateV3Fields(runs) {
+    for (const run of runs) {
+        if (run.changeBindingVersion !== undefined || run.candidateBinding !== undefined || run.executionLease !== undefined) {
+            throw new Error('V2 run state cannot contain candidate V3 fields');
+        }
+    }
+}
+function isErrorCode(error, code) {
+    return typeof error === 'object' && error !== null && 'code' in error && error.code === code;
 }
 function validateReviewFeedbackRunInvariant(run, field) {
     const feedback = run.reviewFeedback;
@@ -579,7 +955,7 @@ function validateReviewFeedbackRunInvariant(run, field) {
         && run.lifecycle !== 'review-ready' && !retainedQuiescentHistory) {
         throw new Error(`${field}.reviewFeedback quiescent phase requires review-ready lifecycle`);
     }
-    if (['frozen', 'repairing'].includes(feedback.phase) && !['implementing', 'reworking', 'checking', 'proving', 'safe-halt'].includes(run.lifecycle)) {
+    if (['frozen', 'repairing'].includes(feedback.phase) && !['implementing', 'reworking', 'checking', 'proving'].includes(run.lifecycle)) {
         throw new Error(`${field}.reviewFeedback active repair phase has invalid lifecycle`);
     }
     if (feedback.phase === 'verified' && run.lifecycle !== 'publishing') {
@@ -606,7 +982,7 @@ function validateReviewFeedbackRunInvariant(run, field) {
 }
 function isLifecycle(value) {
     return typeof value === 'string' && [
-        'claimed', 'triaging', 'routed', 'waiting-human', 'spec-authoring', 'implementing', 'reworking', 'checking', 'proving', 'publishing', 'safe-halt',
+        'claimed', 'triaging', 'routed', 'waiting-human', 'spec-authoring', 'implementing', 'reworking', 'checking', 'proving', 'publishing',
         'review-ready', 'blocked', 'transport-failed', 'cancelled', 'internal-error',
     ].includes(value);
 }
@@ -637,6 +1013,11 @@ function assertGitSha(value, field) {
     if (typeof value !== 'string' || !GIT_SHA_PATTERN.test(value))
         throw new Error(`${field} must be a Git object ID`);
 }
+function assertCandidateRef(value, field) {
+    if (typeof value !== 'string' || !/^refs\/codex-orchestrator\/candidates\/[0-9a-f-]{36}\/[0-9a-f]{64}$/u.test(value)) {
+        throw new Error(`${field} is invalid`);
+    }
+}
 function assertTimestamp(value, field) {
     if (typeof value !== 'string' || Number.isNaN(Date.parse(value)) || new Date(value).toISOString() !== value)
         throw new Error(`${field} is invalid`);