codex-orchestrator 2.0.2 → 2.0.4

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

@@ -3,9 +3,15 @@ import { checkedChangePayloadSha256, } from './checked-change.js';
 import { parseAgentAutoConfig } from './config.js';
 import { canonicalJson, sha256 } from './containment.js';
 import { validateImplementationReport } from './implementation-report.js';
+import { acceptApprovedDirectReview, acceptNeedsWorkDirectReview, beginDirectReviewRepair, createInitialDirectReview, directReviewClosureRequestSha256, directReviewTargetFingerprint, launchDirectReviewInvocation, prepareDirectReviewClosure, prepareDirectReviewInvocation, projectTerminalDirectReview, } from './direct-delivery.js';
 import { ProofQuiescenceError } from './acceptance-proof.js';
+import { RouteInitializationUnrecoverableError, WorkflowGenerationUnrecoverableError, } from './run-store.js';
+import { initialRouteExecution, } from './route-coordinator.js';
+import { downstreamLifecycleForRoute, validateRouteTransition, validateTrustedAnswerResumeTransition, } from './route-decision.js';
 export class OwnerLockSafetyError extends Error {
 }
+export class OwnerLockContentionError extends Error {
+}
 export class RunIssue {
     dependencies;
     signal;
@@ -245,7 +251,10 @@ export class RunIssue {
         const evidence = await this.dependencies.writeEvidence({ runId, code: 'review-ready', summary: pullRequest.url });
         const outcome = { status: 'review-ready', pullRequestUrl: pullRequest.url, evidencePath: evidence.path };
         try {
-            await this.persist(active, { lifecycle: 'review-ready', intent: undefined, outcomeEvidenceId: evidence.id, terminalOutcome: outcome });
+            await this.persist(active, {
+                lifecycle: 'review-ready', intent: undefined, outcomeEvidenceId: evidence.id, terminalOutcome: outcome,
+                ...(active.record.waitingHuman ? { waitingHuman: terminalWaiting(active.record.waitingHuman, { status: 'review-ready' }) } : {}),
+            });
         }
         catch {
             throw new PostEffectStateError(active);
@@ -267,6 +276,12 @@ export class RunIssue {
                 owner = await this.dependencies.ownerLock.acquire({ canonicalRepository, targetRoot });
             }
             catch (error) {
+                if (error instanceof OwnerLockContentionError) {
+                    const evidence = await this.dependencies.writeEvidence({
+                        runId: `issue-${input.issueNumber}`, code: 'owner-contention', summary: 'A known live owner is still running.',
+                    });
+                    return { status: 'requeued', reason: 'owner-contention', evidencePath: evidence.path };
+                }
                 if (error instanceof OwnerLockSafetyError) {
                     const evidence = await this.dependencies.writeEvidence({
                         runId: `issue-${input.issueNumber}`,
@@ -348,20 +363,54 @@ export class RunIssue {
                             return await this.terminal(active, { status: 'internal-error', code: 'local-git-effect-failed' });
                         }
                     }
-                    active = await this.persist(active, { lifecycle: 'implementing' });
+                    active = await this.initializeClaimedRun(active, issue);
+                    issueSnapshot = structuredClone(active.record.issueSnapshot);
                 }
                 else {
-                    if (existing.lifecycle === 'safe-halt')
-                        return await this.publicationDiverged(active, 'safe-halt-requires-process-absence');
-                    if (!['implementing', 'reworking', 'checking', 'proving'].includes(existing.lifecycle)) {
-                        return await this.terminal(active, { status: 'internal-error', code: 'resume-phase-not-reconciled' });
+                    if (existing.lifecycle === 'safe-halt') {
+                        const process = existing.process;
+                        if (!process)
+                            return await this.publicationDiverged(active, 'safe-halt-process-missing');
+                        try {
+                            await this.dependencies.waitForReviewProcessAbsence(process.processGroupId);
+                        }
+                        catch {
+                            return await this.invokedFailure(active, 'safe-halt-process-absence-unconfirmed');
+                        }
+                        active = await this.persist(active, { lifecycle: process.resumeLifecycle, process: undefined });
                     }
-                    if (existing.cycle >= config.runner.maxCycles) {
-                        return await this.terminal(active, { status: 'blocked', kind: 'exhausted', resumable: true });
+                    if (existing.lifecycle === 'waiting-human') {
+                        const waiting = await this.continueWaitingHuman(active);
+                        if ('result' in waiting)
+                            return waiting.result;
+                        active = waiting.active;
+                        issueSnapshot = structuredClone(active.record.issueSnapshot);
+                        frozenCriteria = structuredClone(active.record.frozenCriteria);
+                    }
+                    if (existing.lifecycle === 'spec-authoring') {
+                        if (!await this.authorized(input.issueNumber, runId, branchName, config))
+                            return await this.revoked(active);
+                        return await this.continueSpecRequired(active);
+                    }
+                    if (!['triaging', 'routed', 'implementing', 'reworking', 'checking', 'proving'].includes(active.record.lifecycle)) {
+                        return await this.terminal(active, { status: 'internal-error', code: 'resume-phase-not-reconciled' });
                     }
                     if (!await this.authorized(input.issueNumber, runId, branchName, config))
                         return await this.revoked(active);
-                    active = await this.startNextCycle(active, [`Recovered interrupted ${existing.lifecycle} phase.`]);
+                    if (active.record.lifecycle !== 'triaging' && active.record.lifecycle !== 'routed') {
+                        if (!active.record.routeExecution || !active.record.routeReceipt)
+                            throw new RouteInitializationUnrecoverableError();
+                        const reviewRecovery = active.record.lifecycle === 'implementing' && active.record.directReview?.status === 'active'
+                            && (active.record.directReview.stage === 'review-full' || active.record.directReview.stage === 'review-closure');
+                        const checkRecovery = active.record.lifecycle === 'checking'
+                            && active.record.directReview?.status === 'clear';
+                        if (!reviewRecovery && !checkRecovery) {
+                            if (active.record.cycle >= config.runner.maxCycles) {
+                                return await this.terminal(active, { status: 'blocked', kind: 'exhausted', resumable: true });
+                            }
+                            active = await this.startNextCycle(active, [`Recovered interrupted ${active.record.lifecycle} phase.`]);
+                        }
+                    }
                 }
             }
             else {
@@ -394,7 +443,20 @@ export class RunIssue {
                 catch {
                     return await this.terminal(active, { status: 'internal-error', code: 'local-git-effect-failed' });
                 }
-                active = await this.persist(active, { lifecycle: 'implementing' });
+                active = await this.initializeClaimedRun(active, issue);
+                issueSnapshot = structuredClone(active.record.issueSnapshot);
+            }
+            if (active.record.lifecycle === 'triaging' || active.record.lifecycle === 'routed') {
+                const routed = await this.routeRun(active, issueSnapshot, frozenCriteria, worktreePath, config, input.issueNumber, branchName);
+                if ('result' in routed)
+                    return routed.result;
+                active = routed.active;
+            }
+            if (active.record.lifecycle !== 'implementing' && active.record.lifecycle !== 'checking') {
+                return await this.terminal(active, { status: 'internal-error', code: 'route-dispatch-not-implementing' });
+            }
+            if (active.record.lifecycle === 'checking' && !active.record.directReview && active.record.routeReceipt?.route === 'direct') {
+                return await this.terminal(active, { status: 'internal-error', code: 'direct-review-state-missing' });
             }
             attemptLoop: while (true) {
                 if (!await this.authorized(input.issueNumber, runId, branchName, config)) {
@@ -402,67 +464,45 @@ export class RunIssue {
                 }
                 if (this.signal.aborted)
                     return await this.terminal(active, { status: 'cancelled' });
-                const implementationBaseline = await this.dependencies.git.snapshot(worktreePath);
-                const deniedPathsBaseline = await this.dependencies.git.fingerprintDeniedPaths(worktreePath, config.deny.readPaths);
-                let implementation = await this.runImplementation({
-                    runId,
-                    worktreePath,
-                    issue: issueSnapshot,
-                    frozenCriteria,
-                    cycle: active.record.cycle,
-                    reworkFindings: active.record.reworkFindings,
-                    repairOnly: false,
-                });
-                if (implementation.kind === 'safe-halt') {
-                    active = await this.persist(active, { lifecycle: 'safe-halt', process: implementation.process });
-                    while (true) {
-                        try {
-                            await implementation.waitForAbsence();
-                            break;
-                        }
-                        catch {
-                            await new Promise((resolveWait) => setTimeout(resolveWait, 25));
-                        }
-                    }
-                    if (await this.dependencies.git.fingerprintDeniedPaths(worktreePath, config.deny.readPaths) !== deniedPathsBaseline) {
-                        return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'denied-path-modified');
-                    }
-                    return await this.terminal(active, { status: 'transport-failed', resumable: false }, 'process-quiescence-delayed');
-                }
-                if (await this.dependencies.git.fingerprintDeniedPaths(worktreePath, config.deny.readPaths) !== deniedPathsBaseline) {
-                    return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'denied-path-modified');
-                }
-                if (implementation.kind === 'transport-failed' && implementation.resumable && active.record.transportRetries === 0) {
-                    const afterTransport = await this.dependencies.git.snapshot(worktreePath);
-                    if (!sameFreshness(implementationBaseline, afterTransport)) {
-                        return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'transport-baseline-changed');
-                    }
-                    active = await this.persist(active, { transportRetries: 1 });
-                    continue attemptLoop;
-                }
-                if (implementation.kind !== 'completed')
-                    return await this.mapImplementationFailure(active, implementation);
-                let report;
-                try {
-                    report = validateImplementationReport(implementation.report);
+                let resumeAtChecks = active.record.lifecycle === 'checking'
+                    && active.record.directReview?.status === 'clear';
+                if (active.record.lifecycle === 'implementing'
+                    && active.record.directReview?.status === 'active'
+                    && (active.record.directReview.stage === 'review-full' || active.record.directReview.stage === 'review-closure')) {
+                    const recovered = await this.recoverDirectReviewInvocation(active);
+                    if ('status' in recovered)
+                        return recovered;
+                    active = recovered;
+                    const reviewed = await this.runDirectReviewFull(active, publicIssueSnapshot(issueSnapshot), frozenCriteria, `recovered-implementation-cycle-${active.record.cycle}`, config.runner.maxCycles);
+                    if ('status' in reviewed)
+                        return reviewed;
+                    active = reviewed;
+                    if (active.record.lifecycle === 'implementing')
+                        continue attemptLoop;
+                    resumeAtChecks = true;
                 }
-                catch {
-                    if (active.record.reportRepairs >= 1) {
-                        return await this.terminal(active, { status: 'internal-error', code: 'implementation-report-malformed' });
-                    }
-                    const repairBaseline = await this.dependencies.git.snapshot(worktreePath);
-                    active = await this.persist(active, { reportRepairs: 1 });
-                    implementation = await this.runImplementation({
+                if (!resumeAtChecks) {
+                    const deniedPathsBaseline = await this.dependencies.git.fingerprintDeniedPaths(worktreePath, config.deny.readPaths);
+                    let implementation = await this.runImplementation({
                         runId,
                         worktreePath,
-                        issue: issueSnapshot,
+                        issue: publicIssueSnapshot(issueSnapshot),
                         frozenCriteria,
                         cycle: active.record.cycle,
-                        reworkFindings: ['The previous implementation report did not match the generated schema.'],
-                        repairOnly: true,
+                        reworkFindings: active.record.reworkFindings,
+                        repairOnly: false,
+                        workflowGeneration: active.record.workflowGeneration,
                     });
                     if (implementation.kind === 'safe-halt') {
-                        active = await this.persist(active, { lifecycle: 'safe-halt', process: implementation.process });
+                        active = await this.persist(active, {
+                            lifecycle: 'safe-halt',
+                            process: {
+                                ...implementation.process,
+                                purpose: 'implementation',
+                                resumeLifecycle: 'implementing',
+                                resumeReviewStage: null,
+                            },
+                        });
                         while (true) {
                             try {
                                 await implementation.waitForAbsence();
@@ -472,33 +512,175 @@ export class RunIssue {
                                 await new Promise((resolveWait) => setTimeout(resolveWait, 25));
                             }
                         }
+                        if (await this.dependencies.git.fingerprintDeniedPaths(worktreePath, config.deny.readPaths) !== deniedPathsBaseline) {
+                            return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'denied-path-modified');
+                        }
                         return await this.terminal(active, { status: 'transport-failed', resumable: false }, 'process-quiescence-delayed');
                     }
+                    if (await this.dependencies.git.fingerprintDeniedPaths(worktreePath, config.deny.readPaths) !== deniedPathsBaseline) {
+                        return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'denied-path-modified');
+                    }
+                    if (implementation.kind === 'transport-failed' && implementation.resumable && active.record.transportRetries === 0) {
+                        active = await this.persist(active, { transportRetries: 1 });
+                        continue attemptLoop;
+                    }
                     if (implementation.kind !== 'completed')
                         return await this.mapImplementationFailure(active, implementation);
-                    const afterRepair = await this.dependencies.git.snapshot(worktreePath);
-                    if (!sameFreshness(repairBaseline, afterRepair)) {
-                        return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'report-repair-modified-worktree');
-                    }
+                    let report;
                     try {
                         report = validateImplementationReport(implementation.report);
                     }
                     catch {
-                        return await this.terminal(active, { status: 'internal-error', code: 'implementation-report-malformed' });
+                        if (active.record.reportRepairs >= 1) {
+                            return await this.terminal(active, { status: 'internal-error', code: 'implementation-report-malformed' });
+                        }
+                        const repairBaseline = await this.dependencies.git.snapshot(worktreePath);
+                        active = await this.persist(active, { reportRepairs: 1 });
+                        implementation = await this.runImplementation({
+                            runId,
+                            worktreePath,
+                            issue: publicIssueSnapshot(issueSnapshot),
+                            frozenCriteria,
+                            cycle: active.record.cycle,
+                            reworkFindings: ['The previous implementation report did not match the generated schema.'],
+                            repairOnly: true,
+                            workflowGeneration: active.record.workflowGeneration,
+                        });
+                        if (implementation.kind === 'safe-halt') {
+                            active = await this.persist(active, {
+                                lifecycle: 'safe-halt',
+                                process: {
+                                    ...implementation.process,
+                                    purpose: 'implementation',
+                                    resumeLifecycle: 'implementing',
+                                    resumeReviewStage: null,
+                                },
+                            });
+                            while (true) {
+                                try {
+                                    await implementation.waitForAbsence();
+                                    break;
+                                }
+                                catch {
+                                    await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+                                }
+                            }
+                            return await this.terminal(active, { status: 'transport-failed', resumable: false }, 'process-quiescence-delayed');
+                        }
+                        if (implementation.kind !== 'completed')
+                            return await this.mapImplementationFailure(active, implementation);
+                        const afterRepair = await this.dependencies.git.snapshot(worktreePath);
+                        if (!sameFreshness(repairBaseline, afterRepair)) {
+                            return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'report-repair-modified-worktree');
+                        }
+                        try {
+                            report = validateImplementationReport(implementation.report);
+                        }
+                        catch {
+                            return await this.terminal(active, { status: 'internal-error', code: 'implementation-report-malformed' });
+                        }
+                    }
+                    if (report.status === 'external-block') {
+                        return await this.terminal(active, { status: 'blocked', kind: 'external', resumable: true });
+                    }
+                    if (await this.dependencies.git.getHead(worktreePath) !== baseSha) {
+                        return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true });
+                    }
+                    const changedFiles = await this.dependencies.git.listChangedFiles(worktreePath);
+                    if (changedFiles.length === 0 || !sameStrings(changedFiles, report.changedFiles)) {
+                        if (changedFiles.length === 0 || active.record.reportRepairs >= 1) {
+                            return await this.terminal(active, { status: 'internal-error', code: 'implementation-change-set-invalid' });
+                        }
+                        const repairBaseline = await this.dependencies.git.snapshot(worktreePath);
+                        active = await this.persist(active, { reportRepairs: 1 });
+                        implementation = await this.runImplementation({
+                            runId,
+                            worktreePath,
+                            issue: publicIssueSnapshot(issueSnapshot),
+                            frozenCriteria,
+                            cycle: active.record.cycle,
+                            reworkFindings: [`The report changedFiles must equal the complete current product change set: ${canonicalJson(changedFiles)}.`],
+                            repairOnly: true,
+                            workflowGeneration: active.record.workflowGeneration,
+                        });
+                        if (implementation.kind === 'safe-halt') {
+                            active = await this.persist(active, {
+                                lifecycle: 'safe-halt',
+                                process: {
+                                    ...implementation.process,
+                                    purpose: 'implementation',
+                                    resumeLifecycle: 'implementing',
+                                    resumeReviewStage: null,
+                                },
+                            });
+                            while (true) {
+                                try {
+                                    await implementation.waitForAbsence();
+                                    break;
+                                }
+                                catch {
+                                    await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+                                }
+                            }
+                            return await this.terminal(active, { status: 'transport-failed', resumable: false }, 'process-quiescence-delayed');
+                        }
+                        if (implementation.kind !== 'completed')
+                            return await this.mapImplementationFailure(active, implementation);
+                        const afterRepair = await this.dependencies.git.snapshot(worktreePath);
+                        if (!sameFreshness(repairBaseline, afterRepair)) {
+                            return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'report-repair-modified-worktree');
+                        }
+                        try {
+                            report = validateImplementationReport(implementation.report);
+                        }
+                        catch {
+                            return await this.terminal(active, { status: 'internal-error', code: 'implementation-report-malformed' });
+                        }
+                        if (report.status === 'external-block') {
+                            return await this.terminal(active, { status: 'blocked', kind: 'external', resumable: true });
+                        }
+                        if (!sameStrings(changedFiles, report.changedFiles)) {
+                            return await this.terminal(active, { status: 'internal-error', code: 'implementation-change-set-invalid' });
+                        }
+                    }
+                    if (active.record.routeReceipt?.route === 'direct') {
+                        const targetFingerprint = directReviewTargetFingerprint({
+                            snapshot: await this.dependencies.git.snapshot(worktreePath),
+                            changedFiles,
+                            routeDecisionSha256: active.record.routeReceipt.decisionSha256,
+                            workflowGenerationHash: active.record.workflowGeneration.generationHash,
+                            cycle: active.record.cycle,
+                            frozenCriteria,
+                        });
+                        if (active.record.directReview?.stage === 'review-repair') {
+                            active = await this.persist(active, {
+                                directReview: prepareDirectReviewClosure(active.record.directReview, targetFingerprint).state,
+                            });
+                        }
+                        else {
+                            const reviewerSessionId = this.dependencies.createReviewSessionId();
+                            assertNonEmptyString(reviewerSessionId, 'reviewerSessionId');
+                            active = await this.persist(active, {
+                                directReview: createInitialDirectReview({
+                                    targetFingerprint,
+                                    codeReviewerSessionId: reviewerSessionId,
+                                }),
+                            });
+                        }
+                        const reviewed = await this.runDirectReviewFull(active, publicIssueSnapshot(issueSnapshot), frozenCriteria, implementation.attemptId ?? `implementation-cycle-${active.record.cycle}`, config.runner.maxCycles);
+                        if ('status' in reviewed)
+                            return reviewed;
+                        active = reviewed;
+                        if (active.record.lifecycle === 'implementing')
+                            continue attemptLoop;
+                    }
+                    else {
+                        active = await this.persist(active, { lifecycle: 'checking' });
                     }
                 }
-                if (report.status === 'external-block') {
-                    return await this.terminal(active, { status: 'blocked', kind: 'external', resumable: true });
-                }
-                if (await this.dependencies.git.getHead(worktreePath) !== baseSha) {
-                    return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true });
-                }
-                const changedFiles = await this.dependencies.git.listChangedFiles(worktreePath);
-                if (changedFiles.length === 0 || !sameStrings(changedFiles, report.changedFiles)) {
-                    return await this.terminal(active, { status: 'internal-error', code: 'implementation-change-set-invalid' });
-                }
-                active = await this.persist(active, { lifecycle: 'checking' });
                 for (const [id, command] of Object.entries(config.checks)) {
+                    if (active.record.checks.some((check) => check.id === id && check.status === 'passed'))
+                        continue;
                     if (this.signal.aborted)
                         return await this.terminal(active, { status: 'cancelled' });
                     let check;
@@ -516,12 +698,38 @@ export class RunIssue {
                         if (active.record.cycle >= config.runner.maxCycles) {
                             return await this.terminal(active, { status: 'blocked', kind: 'exhausted', resumable: true });
                         }
-                        active = await this.startNextCycle(active, [`Check ${id} failed:\n${check.output.toString('utf8').slice(0, 8 * 1024)}`]);
+                        const summary = `Check ${id} failed:\n${check.output.toString('utf8').slice(0, 8 * 1024)}`;
+                        active = await this.startNextCycle(active, [summary], [{
+                                provenance: 'check', sourceId: `check:${id}:${row.outputSha256}`, summary,
+                                affectedContracts: ['configured-checks'],
+                            }]);
                         continue attemptLoop;
                     }
                 }
+                let reviewedStageBinding;
                 try {
+                    const reviewedFiles = await this.dependencies.git.listChangedFiles(worktreePath);
+                    const reviewedContentSha256 = await this.dependencies.git.fingerprintChangedFiles(worktreePath, reviewedFiles);
+                    reviewedStageBinding = { files: reviewedFiles, contentSha256: reviewedContentSha256 };
+                    if (active.record.directReview?.status === 'clear') {
+                        const currentFingerprint = directReviewTargetFingerprint({
+                            snapshot: await this.dependencies.git.snapshot(worktreePath),
+                            changedFiles: await this.dependencies.git.listChangedFiles(worktreePath),
+                            routeDecisionSha256: active.record.routeReceipt.decisionSha256,
+                            workflowGenerationHash: active.record.workflowGeneration.generationHash,
+                            cycle: active.record.cycle,
+                            frozenCriteria,
+                        });
+                        if (currentFingerprint !== active.record.directReview.targetFingerprint) {
+                            return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'direct-review-target-drift');
+                        }
+                    }
                     await this.dependencies.git.stageAll(worktreePath);
+                    const stagedFiles = await this.dependencies.git.listChangedFiles(worktreePath);
+                    const stagedContentSha256 = await this.dependencies.git.fingerprintChangedFiles(worktreePath, stagedFiles);
+                    if (!sameStrings(reviewedFiles, stagedFiles) || reviewedContentSha256 !== stagedContentSha256) {
+                        return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'post-stage-review-binding-drift');
+                    }
                 }
                 catch {
                     return await this.terminal(active, { status: 'internal-error', code: 'local-git-effect-failed' });
@@ -531,6 +739,11 @@ export class RunIssue {
                 }
                 const proofChangedFiles = await this.dependencies.git.listChangedFiles(worktreePath);
                 const freshness = await this.dependencies.git.snapshot(worktreePath);
+                const proofContentSha256 = await this.dependencies.git.fingerprintChangedFiles(worktreePath, proofChangedFiles);
+                if (!reviewedStageBinding || !sameStrings(reviewedStageBinding.files, proofChangedFiles)
+                    || reviewedStageBinding.contentSha256 !== proofContentSha256) {
+                    return await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: true }, 'checked-change-review-binding-drift');
+                }
                 const payload = {
                     version: 1,
                     canonicalRepository,
@@ -546,7 +759,7 @@ export class RunIssue {
                     changedFiles: proofChangedFiles,
                     checks: active.record.checks.map((check) => ({ ...check, status: 'passed' })),
                     checkPolicySha256: sha256(canonicalJson(config.checks)),
-                    packageVersion: this.dependencies.packageVersion,
+                    packageVersion: active.record.packageVersion,
                     proofSchemaVersion: 1,
                 };
                 const checkedChange = this.dependencies.checkedChangeMint.mint(payload);
@@ -556,7 +769,13 @@ export class RunIssue {
                 active = await this.persist(active, { lifecycle: 'proving', checkedChangeSha256, proofId });
                 let proof;
                 try {
-                    proof = await this.dependencies.proof.proveChange({ proofId, issue: issueSnapshot, frozenCriteria, checkedChange });
+                    proof = await this.dependencies.proof.proveChange({
+                        proofId,
+                        issue: publicIssueSnapshot(issueSnapshot),
+                        frozenCriteria,
+                        checkedChange,
+                        workflowGeneration: structuredClone(active.record.workflowGeneration),
+                    });
                 }
                 catch (error) {
                     if (error instanceof ProofQuiescenceError) {
@@ -573,6 +792,9 @@ export class RunIssue {
                                     untrackedContentSha256: freshness.untrackedContentSha256,
                                     worktreeIdentity: freshness.worktreeIdentity,
                                 },
+                                purpose: 'proof',
+                                resumeLifecycle: 'proving',
+                                resumeReviewStage: null,
                             },
                         });
                         while (true) {
@@ -594,7 +816,12 @@ export class RunIssue {
                     if (active.record.cycle >= config.runner.maxCycles) {
                         return await this.terminal(active, { status: 'blocked', kind: 'exhausted', resumable: true });
                     }
-                    active = await this.startNextCycle(active, proof.findings);
+                    active = await this.startNextCycle(active, proof.findings, proof.findings.map((summary) => ({
+                        provenance: 'proof',
+                        sourceId: `proof:${proofId}:${sha256(summary)}`,
+                        summary,
+                        affectedContracts: ['acceptance-proof'],
+                    })));
                     continue attemptLoop;
                 }
                 if (proof.status !== 'passed')
@@ -608,12 +835,23 @@ export class RunIssue {
             if (!active && error instanceof TransportReadError) {
                 return await this.preClaimTransport(input.issueNumber);
             }
+            if (!active && error instanceof WorkflowGenerationUnrecoverableError) {
+                return await this.preClaimInternal('workflow-generation-unrecoverable', input.issueNumber);
+            }
             if (active && error instanceof PostEffectStateError) {
                 return await this.invokedFailure(error.active, 'post-effect-state-write-failed');
             }
             if (active && error instanceof TransportReadError) {
                 return await this.invokedFailure(active, 'authorization-read-failed');
             }
+            if (active && error instanceof RouteInitializationUnrecoverableError) {
+                const evidence = await this.dependencies.writeEvidence({
+                    runId: active.record.runId,
+                    code: 'route-initialization-unrecoverable',
+                    summary: 'The claimed run cannot be safely initialized without product-state ambiguity.',
+                });
+                return { status: 'blocked', kind: 'safety', resumable: false, evidencePath: evidence.path };
+            }
             if (active) {
                 try {
                     return await this.terminal(active, { status: 'internal-error', code: 'state-write-failed' });
@@ -641,6 +879,320 @@ export class RunIssue {
             }
         }
     }
+    async initializeClaimedRun(active, issue) {
+        if (active.record.lifecycle !== 'claimed'
+            || active.record.process
+            || active.record.intent
+            || active.record.routeExecution
+            || active.record.routeReceipt) {
+            throw new RouteInitializationUnrecoverableError();
+        }
+        const [snapshot, changedFiles] = await Promise.all([
+            this.dependencies.git.snapshot(active.record.worktreePath),
+            this.dependencies.git.listChangedFiles(active.record.worktreePath),
+        ]);
+        if (snapshot.headSha !== active.record.baseSha || changedFiles.length !== 0) {
+            throw new RouteInitializationUnrecoverableError();
+        }
+        try {
+            await this.dependencies.verifyWorkflowGeneration(active.record.workflowGeneration);
+        }
+        catch {
+            throw new RouteInitializationUnrecoverableError();
+        }
+        const issueSnapshot = issue?.state === 'OPEN' ? snapshotIssue(issue) : active.record.issueSnapshot;
+        return this.persist(active, { lifecycle: 'triaging', routeExecution: initialRouteExecution(), issueSnapshot });
+    }
+    async routeRun(starting, issue, frozenCriteria, worktreePath, config, issueNumber, branchName) {
+        let active = starting;
+        while (active.record.lifecycle === 'triaging') {
+            const state = {
+                read: async () => requireRouteExecution(active.record.routeExecution),
+                compareAndSwap: async (expected, next) => {
+                    if (!sameRouteExecution(active.record.routeExecution, expected))
+                        return false;
+                    active = await this.persist(active, { routeExecution: structuredClone(next) });
+                    return true;
+                },
+                complete: async (expected, next, receipt) => {
+                    if (!sameRouteExecution(active.record.routeExecution, expected))
+                        return false;
+                    active = await this.persist(active, {
+                        lifecycle: 'routed',
+                        routeExecution: structuredClone(next),
+                        routeReceipt: structuredClone(receipt),
+                    });
+                    return true;
+                },
+                cancel: async (expected) => {
+                    if (!sameRouteExecution(active.record.routeExecution, expected))
+                        return false;
+                    const evidence = await this.dependencies.writeEvidence({
+                        runId: active.record.runId,
+                        code: 'cancelled',
+                        summary: 'Routing was cancelled.',
+                    });
+                    active = await this.persist(active, {
+                        lifecycle: 'cancelled',
+                        routeExecution: undefined,
+                        routeReceipt: undefined,
+                        outcomeEvidenceId: evidence.id,
+                        terminalOutcome: { status: 'cancelled', evidencePath: evidence.path },
+                        ...(active.record.waitingHuman ? { waitingHuman: terminalWaiting(active.record.waitingHuman, { status: 'cancelled' }) } : {}),
+                    });
+                    return true;
+                },
+            };
+            const result = await this.dependencies.routeCoordinator.run({
+                state,
+                runId: active.record.runId,
+                worktreePath,
+                workflowGeneration: structuredClone(active.record.workflowGeneration),
+                promptFacts: [
+                    `issue=${canonicalJson(issue)}`,
+                    `frozenCriteria=${canonicalJson(frozenCriteria)}`,
+                    `canonicalRepository=${active.record.canonicalRepository}`,
+                    `baseSha=${active.record.baseSha}`,
+                    ...(active.record.waitingHuman?.phase === 'resumed' ? [
+                        `trustedAnswer=${canonicalJson(active.record.waitingHuman.trustedAnswer)}`,
+                        `priorWaitingRoute=${active.record.waitingHuman.history.at(-1)?.routeReceipt.decisionSha256 ?? ''}`,
+                    ] : []),
+                ],
+                signal: this.signal,
+            });
+            if (result.status === 'repairable' || result.status === 'retryable')
+                continue;
+            if (result.status === 'safe-halt') {
+                active = await this.persist(active, {
+                    lifecycle: 'safe-halt',
+                    process: {
+                        ...result.process,
+                        purpose: 'route',
+                        resumeLifecycle: 'triaging',
+                        resumeReviewStage: null,
+                    },
+                });
+                while (true) {
+                    try {
+                        await result.waitForAbsence();
+                        break;
+                    }
+                    catch {
+                        await new Promise((resolveWait) => setTimeout(resolveWait, 25));
+                    }
+                }
+                const after = await this.dependencies.git.snapshot(worktreePath);
+                if (!sameFreshness(result.process.baseline, after)) {
+                    return { result: await this.terminal(active, { status: 'blocked', kind: 'safety', resumable: false }, 'report-operation-worktree-mutated') };
+                }
+                return { result: await this.terminal(active, { status: 'transport-failed', resumable: false }, 'process-quiescence-delayed') };
+            }
+            if (result.status === 'cancelled') {
+                if (!active.record.terminalOutcome)
+                    throw new Error('route cancellation was not persisted');
+                return { result: publicOutcome(active.record.terminalOutcome) };
+            }
+            if (result.status === 'blocked') {
+                return { result: await this.terminal(active, {
+                        status: 'blocked',
+                        kind: result.kind,
+                        resumable: result.kind !== 'exhausted',
+                    }, result.code) };
+            }
+            if (active.record.lifecycle !== 'routed' || !active.record.routeReceipt) {
+                return { result: await this.terminal(active, { status: 'internal-error', code: 'route-completion-not-persisted' }) };
+            }
+        }
+        if (active.record.lifecycle !== 'routed' || !active.record.routeReceipt) {
+            return { result: await this.terminal(active, { status: 'internal-error', code: 'route-state-not-dispatchable' }) };
+        }
+        try {
+            if (!await this.authorized(issueNumber, active.record.runId, branchName, config)) {
+                return { result: await this.revoked(active) };
+            }
+        }
+        catch (error) {
+            if (error instanceof TransportReadError)
+                return { result: await this.invokedFailure(active, 'authorization-read-failed') };
+            throw error;
+        }
+        const receipt = structuredClone(active.record.routeReceipt);
+        const lifecycle = downstreamLifecycleForRoute(receipt, active.record.workflowGeneration.generationHash);
+        validateRouteTransition({
+            lifecycle: 'routed',
+            routeExecution: active.record.routeExecution,
+            routeReceipt: receipt,
+            generationHash: active.record.workflowGeneration.generationHash,
+        }, {
+            lifecycle,
+            routeExecution: active.record.routeExecution,
+            routeReceipt: receipt,
+            generationHash: active.record.workflowGeneration.generationHash,
+        });
+        if (receipt.route !== 'awaiting-user')
+            active = await this.persist(active, { lifecycle });
+        try {
+            if (!await this.authorized(issueNumber, active.record.runId, branchName, config)) {
+                return { result: await this.revoked(active) };
+            }
+        }
+        catch (error) {
+            if (error instanceof TransportReadError)
+                return { result: await this.invokedFailure(active, 'authorization-read-failed') };
+            throw error;
+        }
+        const context = {
+            runId: active.record.runId,
+            issue: structuredClone(active.record.issueSnapshot),
+            frozenCriteria: structuredClone(active.record.frozenCriteria),
+            worktreePath,
+            workflowGeneration: structuredClone(active.record.workflowGeneration),
+            receipt,
+        };
+        if (receipt.route === 'awaiting-user') {
+            const waiting = await this.dependencies.routeContinuations.awaitingUser(context, this.waitingState(() => active, (next) => { active = next; }), this.signal);
+            const mapped = await this.mapWaitingResult(active, waiting);
+            if ('result' in mapped)
+                return mapped;
+            return this.routeRun(mapped.active, mapped.active.record.issueSnapshot, mapped.active.record.frozenCriteria, worktreePath, config, issueNumber, branchName);
+        }
+        const continuation = receipt.route === 'direct'
+            ? await this.dependencies.routeContinuations.direct(context)
+            : await this.dependencies.routeContinuations.specRequired(context, this.specState(() => active, (next) => { active = next; }), this.signal);
+        if (continuation.status === 'cancelled')
+            return { result: await this.terminal(active, { status: 'cancelled' }) };
+        if (continuation.status === 'blocked') {
+            return { result: await this.terminal(active, {
+                    status: 'blocked', kind: continuation.kind, resumable: continuation.kind !== 'exhausted',
+                }, continuation.code) };
+        }
+        if (continuation.status === 'retryable') {
+            return { result: await this.terminal(active, { status: 'transport-failed', resumable: true }, continuation.code) };
+        }
+        if (receipt.route !== 'direct') {
+            const specContinuation = continuation;
+            if (specContinuation.status !== 'completed')
+                return { result: await this.terminal(active, { status: 'internal-error', code: 'spec-freeze-receipt-missing' }) };
+            const evidence = await this.dependencies.writeEvidence({ runId: active.record.runId, code: 'spec-frozen', summary: specContinuation.receipt.receiptSha256 });
+            return { result: { status: 'spec-frozen', receipt: specContinuation.receipt, evidencePath: evidence.path } };
+        }
+        return { active };
+    }
+    waitingState(readActive, writeActive) {
+        return {
+            read: async () => structuredClone(readActive().record.waitingHuman),
+            compareAndSwap: async (expected, next) => {
+                const active = readActive();
+                const observed = active.record.waitingHuman;
+                if (observed === undefined || expected === undefined) {
+                    if (observed !== expected)
+                        return false;
+                }
+                else if (canonicalJson(observed) !== canonicalJson(expected))
+                    return false;
+                const saved = await this.persist(active, {
+                    ...(active.record.lifecycle === 'routed'
+                        && (expected === undefined || (expected.phase === 'resumed' && next.phase !== 'resumed' && next.phase !== 'history-only'))
+                        ? { lifecycle: 'waiting-human' }
+                        : {}),
+                    waitingHuman: structuredClone(next),
+                });
+                writeActive(saved);
+                return true;
+            },
+        };
+    }
+    specState(readActive, writeActive) {
+        return {
+            read: async () => structuredClone(readActive().record.specDelivery),
+            compareAndSwap: async (expected, next) => {
+                const active = readActive();
+                const observed = active.record.specDelivery;
+                if (observed === undefined || expected === undefined) {
+                    if (observed !== expected)
+                        return false;
+                }
+                else if (canonicalJson(observed) !== canonicalJson(expected))
+                    return false;
+                const saved = await this.persist(active, { specDelivery: structuredClone(next) });
+                writeActive(saved);
+                return true;
+            },
+        };
+    }
+    async continueSpecRequired(active) {
+        if (!active.record.routeReceipt || active.record.routeReceipt.route !== 'spec-required') {
+            return await this.terminal(active, { status: 'internal-error', code: 'spec-route-missing' });
+        }
+        let current = active;
+        const context = {
+            runId: current.record.runId, issue: structuredClone(current.record.issueSnapshot),
+            frozenCriteria: structuredClone(current.record.frozenCriteria), worktreePath: current.record.worktreePath,
+            workflowGeneration: structuredClone(current.record.workflowGeneration), receipt: structuredClone(current.record.routeReceipt),
+        };
+        const result = await this.dependencies.routeContinuations.specRequired(context, this.specState(() => current, (next) => { current = next; }), this.signal);
+        if (result.status === 'completed') {
+            const evidence = await this.dependencies.writeEvidence({ runId: current.record.runId, code: 'spec-frozen', summary: result.receipt.receiptSha256 });
+            return { status: 'spec-frozen', receipt: result.receipt, evidencePath: evidence.path };
+        }
+        if (result.status === 'cancelled')
+            return await this.terminal(current, { status: 'cancelled' });
+        if (result.status === 'retryable')
+            return await this.terminal(current, { status: 'transport-failed', resumable: true }, result.code);
+        return await this.terminal(current, { status: 'blocked', kind: result.kind, resumable: result.kind !== 'exhausted' }, result.code);
+    }
+    async continueWaitingHuman(active) {
+        if (!active.record.routeReceipt || !active.record.workflowGeneration) {
+            return { result: await this.terminal(active, { status: 'internal-error', code: 'waiting-route-missing' }) };
+        }
+        const context = {
+            runId: active.record.runId,
+            issue: structuredClone(active.record.issueSnapshot),
+            frozenCriteria: structuredClone(active.record.frozenCriteria),
+            worktreePath: active.record.worktreePath,
+            workflowGeneration: structuredClone(active.record.workflowGeneration),
+            receipt: structuredClone(active.record.routeReceipt),
+        };
+        let current = active;
+        const result = await this.dependencies.routeContinuations.awaitingUser(context, this.waitingState(() => current, (next) => { current = next; }), this.signal);
+        return this.mapWaitingResult(current, result);
+    }
+    async mapWaitingResult(active, result) {
+        if (result.status === 'awaiting-answer') {
+            const evidence = await this.dependencies.writeEvidence({ runId: active.record.runId, code: 'awaiting-user', summary: result.questionId });
+            return { result: { status: 'awaiting-user', questionId: result.questionId, answerPrefix: result.answerPrefix, evidencePath: evidence.path } };
+        }
+        if (result.status === 'retryable') {
+            const evidence = await this.dependencies.writeEvidence({ runId: active.record.runId, code: result.code, summary: result.owner });
+            return { result: { status: 'transport-failed', resumable: true, evidencePath: evidence.path } };
+        }
+        if (result.status === 'cancelled')
+            return { result: await this.terminal(active, { status: 'cancelled' }) };
+        if (result.status === 'blocked') {
+            return { result: await this.terminal(active, { status: 'blocked', kind: result.kind, resumable: result.resumable }, result.code) };
+        }
+        const waitingHuman = archiveWaiting(active.record, result.answer, {
+            phase: 'resumed', trustedAnswer: structuredClone(result.answer),
+        });
+        const routeExecution = initialRouteExecution();
+        validateTrustedAnswerResumeTransition({
+            lifecycle: active.record.lifecycle,
+            routeExecution: active.record.routeExecution,
+            routeReceipt: active.record.routeReceipt,
+            generationHash: active.record.workflowGeneration.generationHash,
+        }, {
+            lifecycle: 'triaging', routeExecution, routeReceipt: undefined,
+            generationHash: active.record.workflowGeneration.generationHash,
+        }, active.record.waitingHuman);
+        const resumed = await this.persist(active, {
+            lifecycle: 'triaging',
+            issueSnapshot: structuredClone(active.record.issueSnapshot),
+            routeExecution,
+            routeReceipt: undefined,
+            waitingHuman,
+        });
+        return { active: resumed };
+    }
     async readStrictConfig(targetRoot) {
         const value = await this.dependencies.readConfig(targetRoot);
         return { bytes: Buffer.from(value.bytes), config: parseAgentAutoConfig(structuredClone(value.config)) };
@@ -653,7 +1205,8 @@ export class RunIssue {
             return 'Issue is not open.';
         if (!labels.has(config.github.labels.auto.name))
             return 'Issue lacks the auto label.';
-        if ([config.github.labels.running.name, config.github.labels.blocked.name, config.github.labels.review.name].some((label) => labels.has(label))) {
+        if ([config.github.labels.running.name, config.github.labels.blocked.name, config.github.labels.review.name, config.github.labels.waitingHuman.name]
+            .some((label) => labels.has(label))) {
             return 'Issue already has a terminal or running label.';
         }
         const branchName = `codex/issue-${issue.number}`;
@@ -669,12 +1222,14 @@ export class RunIssue {
     async createRun(input) {
         const state = await this.dependencies.runRecords.read();
         const now = this.timestamp();
+        const workflow = await this.dependencies.createWorkflowGeneration();
         const record = {
             ...input,
             lifecycle: 'claimed', cycle: 1, reportRepairs: 0, transportRetries: 0,
             reworkFindings: [],
-            packageVersion: this.dependencies.packageVersion,
-            skillHashes: structuredClone(this.dependencies.skillHashes),
+            packageVersion: workflow.receipt.packageVersion,
+            workflowGeneration: structuredClone(workflow.receipt),
+            skillHashes: structuredClone(workflow.skillHashes),
             checks: [], createdAt: now, updatedAt: now,
         };
         const saved = await this.dependencies.runRecords.compareAndSwap(state.generation, {
@@ -688,7 +1243,7 @@ export class RunIssue {
             delete record.intent;
         if (Object.hasOwn(changes, 'process') && changes.process === undefined)
             delete record.process;
-        for (const key of ['checkedChangeSha256', 'proofId', 'proofReceipt', 'terminalOutcome', 'outcomeEvidenceId']) {
+        for (const key of ['checkedChangeSha256', 'proofId', 'proofReceipt', 'terminalOutcome', 'outcomeEvidenceId', 'routeExecution', 'routeReceipt']) {
             if (Object.hasOwn(changes, key) && changes[key] === undefined)
                 delete record[key];
         }
@@ -739,19 +1294,230 @@ export class RunIssue {
     }
     async runImplementation(input) {
         try {
-            return await this.dependencies.implementationAgent.run({ ...input, signal: this.signal });
+            return await this.dependencies.implementationAgent.run({
+                ...input,
+                workflowGeneration: structuredClone(input.workflowGeneration),
+                signal: this.signal,
+            });
         }
         catch {
             return { kind: 'internal-error' };
         }
     }
-    async startNextCycle(active, findings) {
+    async runDirectReviewFull(starting, issue, frozenCriteria, implementationAttemptId, maxCycles) {
+        let active = starting;
+        let reportRepair;
+        while (true) {
+            const directReview = active.record.directReview;
+            const routeReceipt = active.record.routeReceipt;
+            if (!directReview || !routeReceipt || routeReceipt.route !== 'direct'
+                || (directReview.stage !== 'review-full' && directReview.stage !== 'review-closure')) {
+                return this.terminal(active, { status: 'internal-error', code: 'direct-review-state-invalid' });
+            }
+            const reviewerSessionId = directReview.review.reviewerSessionId;
+            if (!reviewerSessionId)
+                return this.terminal(active, { status: 'internal-error', code: 'direct-review-session-missing' });
+            const closureRequestSha256 = directReview.stage === 'review-closure'
+                ? directReviewClosureRequestSha256(directReview)
+                : null;
+            const mode = directReview.stage === 'review-closure' ? 'closure' : 'full';
+            const result = await this.dependencies.implementationReviewer.run({
+                runId: active.record.runId,
+                worktreePath: active.record.worktreePath,
+                operation: 'code-review',
+                mode,
+                reviewerSessionId,
+                implementationAttemptId,
+                targetRevision: directReview.targetRevision,
+                targetFingerprint: directReview.targetFingerprint,
+                closureRequestSha256,
+                issue,
+                frozenCriteria,
+                routeReceipt: structuredClone(routeReceipt),
+                defects: structuredClone(directReview.review.defects),
+                affectedDefectIds: [...directReview.review.affectedDefectIds],
+                fixedRepairFindings: directReview.repairFindings.filter((finding) => finding.status === 'fixed')
+                    .map((finding) => ({ id: finding.id, affectedContracts: [...finding.affectedContracts] })),
+                mandatoryCoverage: directReview.stage === 'review-closure'
+                    ? [...directReview.review.coverage]
+                    : ['acceptance-criteria', 'correctness', 'test-quality'],
+                workflowGeneration: structuredClone(active.record.workflowGeneration),
+                repairOnly: reportRepair !== undefined,
+                originalReportSha256: reportRepair?.originalReportSha256 ?? null,
+                validationDiagnostic: reportRepair?.diagnostic ?? null,
+                originalReportBytes: reportRepair?.originalReportBytes ?? null,
+                signal: this.signal,
+                onPrepared: async (invocation) => {
+                    const current = active.record.directReview;
+                    if (!current)
+                        throw new Error('direct review disappeared before prepare');
+                    active = await this.persist(active, {
+                        directReview: prepareDirectReviewInvocation(current, invocation),
+                    });
+                },
+                onLaunched: async (invocation) => {
+                    const current = active.record.directReview;
+                    if (!current)
+                        throw new Error('direct review disappeared before launch');
+                    active = await this.persist(active, {
+                        directReview: launchDirectReviewInvocation(current, invocation),
+                    });
+                },
+            });
+            if (result.kind === 'completed') {
+                const current = active.record.directReview;
+                if (!current)
+                    return this.terminal(active, { status: 'internal-error', code: 'direct-review-result-orphaned' });
+                if (result.report.verdict === 'needs-work') {
+                    if (active.record.cycle >= maxCycles) {
+                        return this.terminal(active, { status: 'blocked', kind: 'exhausted', resumable: true }, 'direct-review-repair-exhausted');
+                    }
+                    const repaired = acceptNeedsWorkDirectReview(current, result.report, result.artifactSha256);
+                    const findings = [
+                        ...result.report.defects
+                            .filter((defect) => defect.status === 'open' || defect.status === 'reopened')
+                            .map((defect) => `${defect.id}: ${defect.failure}\nRepair: ${defect.repair}`),
+                        ...repaired.repairFindings
+                            .filter((finding) => finding.status === 'reopened')
+                            .map((finding) => `${finding.id}: ${finding.summary}`),
+                    ];
+                    return this.persist(active, {
+                        lifecycle: 'implementing',
+                        cycle: (active.record.cycle + 1),
+                        directReview: repaired,
+                        reworkFindings: findings,
+                        checks: [],
+                        checkedChangeSha256: undefined,
+                        proofId: undefined,
+                        proofReceipt: undefined,
+                    });
+                }
+                if (result.report.verdict !== 'approved')
+                    return this.terminal(active, { status: 'blocked', kind: 'safety', resumable: false }, 'direct-review-rejected');
+                return this.persist(active, {
+                    lifecycle: 'checking',
+                    directReview: acceptApprovedDirectReview(current, result.report, result.artifactSha256),
+                });
+            }
+            if (result.kind === 'report-invalid') {
+                const current = active.record.directReview;
+                if (!current)
+                    return this.terminal(active, { status: 'internal-error', code: 'direct-review-result-orphaned' });
+                if (current.review.reportRepairs >= 1 || reportRepair) {
+                    return this.terminal(active, { status: 'internal-error', code: 'direct-review-report-malformed' });
+                }
+                const { invocation: _invocation, ...withoutInvocation } = structuredClone(current);
+                active = await this.persist(active, {
+                    directReview: {
+                        ...withoutInvocation,
+                        review: { ...withoutInvocation.review, reportRepairs: 1 },
+                    },
+                });
+                reportRepair = {
+                    originalReportSha256: result.originalReportSha256,
+                    originalReportBytes: Buffer.from(result.originalReportBytes),
+                    diagnostic: result.diagnostic,
+                };
+                continue;
+            }
+            if (result.kind === 'transport-failed') {
+                const current = active.record.directReview;
+                if (!current || current.review.transportRetries >= 1) {
+                    return this.terminal(active, { status: 'blocked', kind: 'exhausted', resumable: true }, 'direct-review-transport-exhausted');
+                }
+                const { invocation: _invocation, ...withoutInvocation } = structuredClone(current);
+                active = await this.persist(active, {
+                    directReview: {
+                        ...withoutInvocation,
+                        review: { ...withoutInvocation.review, transportRetries: 1 },
+                    },
+                });
+                continue;
+            }
+            if (result.kind === 'safe-halt') {
+                active = await this.persist(active, {
+                    lifecycle: 'safe-halt',
+                    process: {
+                        ...result.process,
+                        purpose: 'code-review',
+                        resumeLifecycle: 'implementing',
+                        resumeReviewStage: directReview.stage,
+                    },
+                });
+                try {
+                    await result.waitForAbsence();
+                }
+                catch {
+                    return this.terminal(active, { status: 'transport-failed', resumable: false }, 'direct-review-quiescence-unconfirmed');
+                }
+                return this.terminal(active, { status: 'transport-failed', resumable: false }, 'direct-review-quiescence-delayed');
+            }
+            if (result.kind === 'cancelled')
+                return this.terminal(active, { status: 'cancelled' });
+            return this.terminal(active, { status: 'internal-error', code: result.code });
+        }
+    }
+    async recoverDirectReviewInvocation(starting) {
+        const directReview = starting.record.directReview;
+        const invocation = directReview?.invocation;
+        if (!directReview || !invocation)
+            return starting;
+        const { invocation: _invocation, ...withoutInvocation } = structuredClone(directReview);
+        if (invocation.status === 'prepared') {
+            return this.persist(starting, { directReview: withoutInvocation });
+        }
+        if (invocation.status === 'launched') {
+            try {
+                await this.dependencies.waitForReviewProcessAbsence(invocation.processGroupId);
+            }
+            catch {
+                return this.terminal(starting, { status: 'blocked', kind: 'safety', resumable: false }, 'direct-review-process-absence-unconfirmed');
+            }
+            if (directReview.review.transportRetries >= 1) {
+                return this.terminal(starting, { status: 'blocked', kind: 'exhausted', resumable: true }, 'direct-review-transport-exhausted');
+            }
+            return this.persist(starting, {
+                directReview: {
+                    ...withoutInvocation,
+                    review: { ...withoutInvocation.review, transportRetries: 1 },
+                },
+            });
+        }
+        return this.persist(starting, { directReview: withoutInvocation });
+    }
+    async startNextCycle(active, findings, sources) {
+        if (active.record.directReview?.status === 'clear') {
+            const fallbackProvenance = active.record.lifecycle === 'proving' ? 'proof' : 'check';
+            const normalizedSources = sources ?? findings.map((summary) => ({
+                provenance: fallbackProvenance,
+                sourceId: `${fallbackProvenance}:recovery:${sha256(summary)}`,
+                summary,
+                affectedContracts: [fallbackProvenance === 'proof' ? 'acceptance-proof' : 'configured-checks'],
+            }));
+            const repairFindings = normalizedSources.map((source) => ({
+                id: source.sourceId,
+                provenance: source.provenance,
+                sourceId: source.sourceId,
+                targetRevision: active.record.directReview.targetRevision,
+                summary: source.summary,
+                affectedContracts: source.affectedContracts,
+                status: 'open',
+            }));
+            return this.persist(active, {
+                lifecycle: 'implementing',
+                cycle: (active.record.cycle + 1),
+                reworkFindings: [...findings],
+                directReview: beginDirectReviewRepair(active.record.directReview, repairFindings),
+                checks: [],
+                checkedChangeSha256: undefined,
+                proofId: undefined,
+                proofReceipt: undefined,
+            });
+        }
         active = await this.persist(active, { lifecycle: 'reworking', reworkFindings: [...findings] });
         return this.persist(active, {
             lifecycle: 'implementing',
             cycle: (active.record.cycle + 1),
-            packageVersion: this.dependencies.packageVersion,
-            skillHashes: structuredClone(this.dependencies.skillHashes),
             checks: [],
             checkedChangeSha256: undefined,
             proofId: undefined,
@@ -792,6 +1558,38 @@ export class RunIssue {
             outcomeEvidenceId: evidence.id,
             process: undefined,
         };
+        if (outcome.status !== 'review-ready' && active.record.directReview && active.record.directReview.status !== 'terminal') {
+            changes.directReview = projectTerminalDirectReview(active.record.directReview, outcome.status === 'blocked'
+                ? { status: 'blocked', kind: outcome.kind }
+                : { status: outcome.status });
+        }
+        if (active.record.waitingHuman && (active.record.lifecycle === 'waiting-human' || active.record.waitingHuman.phase === 'resumed')) {
+            if (active.record.waitingHuman.phase === 'resumed') {
+                changes.waitingHuman = {
+                    version: 1,
+                    clarificationAttempts: active.record.waitingHuman.clarificationAttempts,
+                    permissionRetries: active.record.waitingHuman.permissionRetries,
+                    effectRetries: structuredClone(active.record.waitingHuman.effectRetries),
+                    history: structuredClone(active.record.waitingHuman.history),
+                    phase: 'history-only',
+                    terminalOutcome: outcome.status === 'blocked'
+                        ? { status: 'blocked', kind: outcome.kind }
+                        : { status: outcome.status },
+                };
+            }
+            else if (outcome.status === 'blocked' || outcome.status === 'cancelled') {
+                changes.waitingHuman = archiveWaiting(active.record, waitingAnswer(active.record.waitingHuman), {
+                    phase: 'history-only',
+                    terminalOutcome: outcome.status === 'cancelled'
+                        ? { status: 'cancelled' }
+                        : { status: 'blocked', kind: outcome.kind },
+                });
+            }
+        }
+        if (active.record.lifecycle === 'triaging' || (active.record.lifecycle === 'safe-halt' && !active.record.routeReceipt)) {
+            changes.routeExecution = undefined;
+            changes.routeReceipt = undefined;
+        }
         if (!retainIntent)
             changes.intent = undefined;
         await this.persist(active, changes);
@@ -835,6 +1633,17 @@ function snapshotIssue(issue) {
         url: issue.url,
         state: 'OPEN',
         labels: sortedUnique(issue.labels),
+        comments: structuredClone(issue.comments),
+    };
+}
+function publicIssueSnapshot(issue) {
+    return {
+        number: issue.number,
+        title: issue.title,
+        body: issue.body,
+        url: issue.url,
+        state: issue.state,
+        labels: [...issue.labels],
     };
 }
 function freezeCriteria(issue) {
@@ -864,11 +1673,72 @@ function findRun(state, runId) {
         throw new Error('persisted run is missing');
     return record;
 }
+function waitingAnswer(waiting) {
+    if ('answerReceipt' in waiting)
+        return structuredClone(waiting.answerReceipt);
+    if (waiting.phase === 'resumed')
+        return structuredClone(waiting.trustedAnswer);
+    return null;
+}
+function archiveWaiting(record, answer, terminal) {
+    const waiting = record.waitingHuman;
+    const routeReceipt = record.routeReceipt;
+    if (!waiting || !routeReceipt)
+        throw new Error('waiting archive requires active route evidence');
+    const question = 'question' in waiting ? waiting.question : 'questionReceipt' in waiting ? waiting.questionReceipt.question : undefined;
+    if (!question)
+        throw new Error('waiting archive requires current question');
+    const questionReceipt = 'questionReceipt' in waiting ? waiting.questionReceipt : null;
+    const entry = {
+        routeReceipt: structuredClone(routeReceipt),
+        question: structuredClone(question),
+        questionReceipt: questionReceipt ? structuredClone(questionReceipt) : null,
+        answerReceipt: answer ? structuredClone(answer) : null,
+        conflictHashes: [...question.conflictHashes],
+    };
+    const history = [...waiting.history];
+    if (history.at(-1)?.question.questionSha256 === question.questionSha256) {
+        if (canonicalJson(history.at(-1)) !== canonicalJson(entry))
+            throw new Error('waiting archive evidence mismatch');
+    }
+    else {
+        history.push(entry);
+    }
+    return {
+        version: 1,
+        clarificationAttempts: waiting.clarificationAttempts,
+        permissionRetries: waiting.permissionRetries,
+        effectRetries: structuredClone(waiting.effectRetries),
+        history,
+        ...terminal,
+    };
+}
+function terminalWaiting(waiting, terminalOutcome) {
+    if (waiting.phase !== 'resumed' && waiting.phase !== 'history-only')
+        throw new Error('terminal waiting projection requires archived history');
+    return {
+        version: 1,
+        clarificationAttempts: waiting.clarificationAttempts,
+        permissionRetries: waiting.permissionRetries,
+        effectRetries: structuredClone(waiting.effectRetries),
+        history: structuredClone(waiting.history),
+        phase: 'history-only',
+        terminalOutcome,
+    };
+}
 function publicOutcome(outcome) {
     if (outcome.status === 'internal-error')
         return { status: 'internal-error', evidencePath: outcome.evidencePath };
     return structuredClone(outcome);
 }
+function requireRouteExecution(value) {
+    if (!value)
+        throw new Error('route execution is missing');
+    return structuredClone(value);
+}
+function sameRouteExecution(left, right) {
+    return left !== undefined && canonicalJson(left) === canonicalJson(right);
+}
 function sameStrings(left, right) {
     const a = [...left].sort();
     const b = [...right].sort();