parallel-codex-tui 0.1.4 → 0.1.6

package/dist/orchestrator/orchestrator.js

@@ -7,10 +7,12 @@ import { routerRuntimeDir } from "../core/paths.js";
 import { classifyRouterFailure, routerFallbackIsTransient } from "../core/router-audit.js";
 import { sanitizeRouterText } from "../core/router-redaction.js";
 import { routeRequestWithCodex, routerCommandLabel, routerProxyContext } from "../core/router.js";
-import { RouteDecisionSchema, TaskMetaSchema, WorkerStatusSchema } from "../domain/schemas.js";
+import { FeatureStatusSchema, RouteDecisionSchema, TaskMetaSchema, WorkerStatusSchema } from "../domain/schemas.js";
 import { getAdapter } from "../workers/registry.js";
-import { appendFeatureDialogue, createFeatureChannel, featureCriticCheckpointIsReusable, featurePromptContext, recordApprovedFindingResolution, requireActorFindingReplies, requireFeatureRevisionFindings, updateFeatureStatus, writeFeatureDecision } from "./collaboration-channel.js";
-import { buildActorPrompt, buildCriticPrompt, buildJudgePrompt, buildMainPrompt, buildWaveActorPrompt, buildWaveCriticPrompt } from "./prompts.js";
+import { workerProvider } from "../workers/provider.js";
+import { appendFeatureDialogue, createFeatureChannel, featureCriticCheckpointIsReusable, featurePromptContext, readFeatureAssignment, recordApprovedFindingResolution, requireActorFindingReplies, requireFeatureRevisionFindings, updateFeatureStatus, writeFeatureAssignment, writeFeatureDecision } from "./collaboration-channel.js";
+import { buildActorPrompt, buildCriticPrompt, buildFinalJudgePrompt, buildJudgePrompt, buildMainPrompt, buildWaveActorPrompt, buildWaveCriticPrompt } from "./prompts.js";
+import { validateFinalJudgeAcceptance } from "./final-acceptance.js";
 import { featureExecutionWaves, parseFeaturePlan } from "./feature-plan.js";
 import { JUDGE_REQUIRED_ARTIFACTS, JUDGE_VALIDATION_FILE, validateJudgeArtifacts } from "./judge-artifacts.js";
 import { buildSupervisorSummary } from "./supervisor-summary.js";
@@ -21,6 +23,9 @@ const JUDGE_ARTIFACTS = [
     ...JUDGE_REQUIRED_ARTIFACTS,
     "features.json"
 ];
+const FINAL_ACCEPTANCE_FILE = "final-acceptance.json";
+const FINAL_ACCEPTANCE_VALIDATION_FILE = "final-acceptance-validation.json";
+const COMPLETION_CONTRACT_FILE = "completion-contract.json";
 class FeatureRunCancelledError extends Error {
     featureId;
     constructor(featureId) {
@@ -29,6 +34,14 @@ class FeatureRunCancelledError extends Error {
         this.name = "FeatureRunCancelledError";
     }
 }
+class FeatureRunPausedError extends Error {
+    featureId;
+    constructor(featureId) {
+        super(`Feature ${featureId} was paused before integration. Completed peer checkpoints were preserved.`);
+        this.featureId = featureId;
+        this.name = "FeatureRunPausedError";
+    }
+}
 export class Orchestrator {
     config;
     sessions;
@@ -108,6 +121,67 @@ export class Orchestrator {
         });
     }
     async retryTask(input) {
+        return this.resumeTaskRun(input);
+    }
+    async resumeFeature(input) {
+        return this.resumeTaskRun(input, input.featureId);
+    }
+    async reassignFeature(input) {
+        if (!featureIdIsSafe(input.featureId)) {
+            throw new Error(`Unsafe feature id: ${input.featureId}`);
+        }
+        const nextProvider = workerProvider(this.config, input.engine).config;
+        if (!nextProvider.assignable) {
+            throw new Error(`Worker provider cannot be assigned to a Feature: ${input.engine}`);
+        }
+        const task = this.sessions.taskFromId(input.taskId);
+        if (!(await readTaskMetaIfValid(task.metaPath))) {
+            throw new Error(`Task session not found: ${input.taskId}`);
+        }
+        if (this.activeFeatureRuns.has(featureRunKey(input.taskId, input.featureId))) {
+            throw new Error(`Feature ${input.featureId} still has an active worker.`);
+        }
+        return this.withTaskRunLease(task, async () => {
+            const meta = await readTaskMetaIfValid(task.metaPath);
+            if (!meta) {
+                throw new Error(`Task session not found: ${input.taskId}`);
+            }
+            if (!new Set(["failed", "cancelled", "paused"]).has(meta.status)) {
+                throw new Error(`Task ${input.taskId} is ${meta.status}; reassign a feature only while its task is failed, cancelled, or paused.`);
+            }
+            if (this.activeFeatureRuns.has(featureRunKey(input.taskId, input.featureId))) {
+                throw new Error(`Feature ${input.featureId} still has an active worker.`);
+            }
+            const featureDir = join(task.dir, "features", input.featureId);
+            const status = await readJson(join(featureDir, "status.json"), FeatureStatusSchema);
+            if (status.task_id !== task.id || status.feature_id !== input.featureId) {
+                throw new Error(`Feature ${input.featureId} does not belong to task ${task.id}.`);
+            }
+            if (status.state === "approved") {
+                throw new Error(`Feature ${input.featureId} is already approved and cannot be reassigned.`);
+            }
+            const route = await this.sessions.readLatestRoute(task);
+            const fallback = {
+                actor: route?.actor_engine ?? this.config.pairing.actor,
+                critic: route?.critic_engine ?? this.config.pairing.critic
+            };
+            const assignmentPath = join(featureDir, "assignment.json");
+            const current = await readFeatureAssignment({ assignmentPath }, fallback);
+            const assignment = await writeFeatureAssignment({ assignmentPath }, input.role === "actor" ? input.engine : current.actor_engine, input.role === "critic" ? input.engine : current.critic_engine);
+            await appendJsonLine(join(task.dir, "dialogue", "actor-critic.jsonl"), {
+                time: new Date().toISOString(),
+                feature_id: input.featureId,
+                turn_id: status.turn_id,
+                type: "feature.assignment_changed",
+                role: input.role,
+                message: `${capitalize(input.role)} reassigned to ${input.engine}.`,
+                paths: { assignment: assignmentPath }
+            });
+            await this.sessions.appendEvent(task, "feature.assignment_changed", `${input.featureId} ${input.role} reassigned to ${input.engine}`);
+            return { featureId: input.featureId, assignment };
+        });
+    }
+    async resumeTaskRun(input, pausedFeatureId) {
         throwIfCancelled(input.signal);
         const task = this.sessions.taskFromId(input.taskId);
         if (!(await readTaskMetaIfValid(task.metaPath))) {
@@ -119,8 +193,21 @@ export class Orchestrator {
             if (!meta) {
                 throw new Error(`Task session not found: ${input.taskId}`);
             }
-            if (meta.status !== "failed" && meta.status !== "cancelled") {
-                throw new Error(`Task ${input.taskId} is ${meta.status}; only failed or cancelled tasks can be retried.`);
+            const retryableStates = pausedFeatureId
+                ? new Set(["paused"])
+                : new Set(["failed", "cancelled", "paused"]);
+            if (!retryableStates.has(meta.status)) {
+                throw new Error(pausedFeatureId
+                    ? `Task ${input.taskId} is ${meta.status}; only a paused task can resume a feature.`
+                    : `Task ${input.taskId} is ${meta.status}; only failed, cancelled, or paused tasks can be retried.`);
+            }
+            if (pausedFeatureId) {
+                const featureStatus = await readJson(join(task.dir, "features", pausedFeatureId, "status.json"), FeatureStatusSchema);
+                if (featureStatus.task_id !== task.id
+                    || featureStatus.feature_id !== pausedFeatureId
+                    || featureStatus.state !== "paused") {
+                    throw new Error(`Feature ${pausedFeatureId} is not paused in task ${task.id}.`);
+                }
             }
             const turn = await this.sessions.latestTurn(task);
             if (!turn) {
@@ -141,7 +228,9 @@ export class Orchestrator {
             input.onRoute?.(route);
             throwIfCancelled(input.signal);
             await this.sessions.recordLatestRoute(task, route);
-            await this.sessions.appendEvent(task, "task.retrying", `Retrying turn ${turn.turnId}`);
+            await this.sessions.appendEvent(task, pausedFeatureId ? "feature.resume_requested" : "task.retrying", pausedFeatureId
+                ? `Resuming ${pausedFeatureId} in turn ${turn.turnId}`
+                : `Retrying turn ${turn.turnId}`);
             return turn.turnId === "0001"
                 ? this.runInitialTask(executionInput, task, route, turn, workers)
                 : this.runPairTask(executionInput, task, route, turn, workers);
@@ -149,7 +238,7 @@ export class Orchestrator {
     }
     async canRetryTask(taskId) {
         const meta = await readTaskMetaIfValid(this.sessions.taskFromId(taskId).metaPath);
-        return meta?.status === "failed" || meta?.status === "cancelled";
+        return meta?.status === "failed" || meta?.status === "cancelled" || meta?.status === "paused";
     }
     async cancelFeature(taskId, featureId) {
         const active = this.activeFeatureRuns.get(featureRunKey(taskId, featureId));
@@ -172,6 +261,27 @@ export class Orchestrator {
             role: active.role
         };
     }
+    async pauseFeature(taskId, featureId) {
+        const active = this.activeFeatureRuns.get(featureRunKey(taskId, featureId));
+        if (!active || active.cancelRequested) {
+            return { requested: false, featureId };
+        }
+        if (!active.pauseRequested) {
+            active.pauseRequested = true;
+            active.controller.abort();
+            try {
+                await this.sessions.appendEvent(this.sessions.taskFromId(taskId), "feature.pause_requested", `Pause requested for ${featureId} ${active.role}`);
+            }
+            catch {
+                // Pausing must not wait on optional audit evidence.
+            }
+        }
+        return {
+            requested: true,
+            featureId,
+            role: active.role
+        };
+    }
     async withTaskRunLease(task, run) {
         let lease;
         try {
@@ -288,7 +398,7 @@ export class Orchestrator {
             });
         }
         return workers.sort((left, right) => (workerTurnOrder(left) - workerTurnOrder(right)
-            || workerRoleOrder(left.role) - workerRoleOrder(right.role)
+            || workerStageOrder(left) - workerStageOrder(right)
             || left.id.localeCompare(right.id)));
     }
     async runInitialTask(input, task, route, turn, workers) {
@@ -317,6 +427,8 @@ export class Orchestrator {
                     request: input.request,
                     judgeDir: judge.dir,
                     feature,
+                    actorEngine: route.actor_engine,
+                    criticEngine: route.critic_engine,
                     resume: input.retry
                 })));
                 return await this.runFeaturePlan(input, task, route, turn, workers, judge, featurePlan, features);
@@ -326,6 +438,8 @@ export class Orchestrator {
                 turn,
                 request: input.request,
                 judgeDir: judge.dir,
+                actorEngine: route.actor_engine,
+                criticEngine: route.critic_engine,
                 resume: input.retry
             });
             features = [feature];
@@ -359,6 +473,8 @@ export class Orchestrator {
                     request: input.request,
                     judgeDir: judge.dir,
                     feature,
+                    actorEngine: route.actor_engine,
+                    criticEngine: route.critic_engine,
                     resume: input.retry
                 })));
                 return await this.runFeaturePlan(input, task, route, turn, workers, judge, featurePlan, features);
@@ -368,6 +484,8 @@ export class Orchestrator {
                 turn,
                 request: input.request,
                 judgeDir: judge.dir,
+                actorEngine: route.actor_engine,
+                criticEngine: route.critic_engine,
                 resume: input.retry
             });
             features = [feature];
@@ -442,6 +560,13 @@ export class Orchestrator {
     }
     async runFeaturePlan(input, task, route, turn, workers, judge, plan, features) {
         const channels = new Map(plan.features.map((definition, index) => [definition.id, features[index]]));
+        const assignments = new Map(await Promise.all(features.map(async (feature) => [
+            feature.id,
+            await readFeatureAssignment(feature, {
+                actor: route.actor_engine,
+                critic: route.critic_engine
+            })
+        ])));
         const summaries = [];
         const waveReviews = [];
         const changedPaths = new Set();
@@ -492,7 +617,7 @@ export class Orchestrator {
             await this.sessions.updateTaskStatus(task, "actor_running");
             const actorRunById = new Map();
             if (restoredWave) {
-                const restoredActors = await Promise.all(wave.map((definition) => this.loadCompletedFeatureActor(task, route.actor_engine, definition, requiredChannel(channels, definition))));
+                const restoredActors = await Promise.all(wave.map((definition) => this.loadCompletedFeatureActor(task, requiredFeatureAssignment(assignments, requiredChannel(channels, definition)).actor_engine, definition, requiredChannel(channels, definition))));
                 for (const actorRun of restoredActors) {
                     if (actorRun) {
                         actorRunById.set(actorRun.definition.id, actorRun);
@@ -511,7 +636,7 @@ export class Orchestrator {
             }
             const freshActorRuns = await mapWithConcurrency(pendingActors, concurrency, async (definition) => {
                 const channel = requiredChannel(channels, definition);
-                const actor = await this.runActor(input, task, route.actor_engine, judge.dir, workers, turn, channel, undefined, true, requiredFeatureWorkspace(workspaceWave.featureDirs, channel));
+                const actor = await this.runActor(input, task, requiredFeatureAssignment(assignments, channel).actor_engine, judge.dir, workers, turn, channel, undefined, true, requiredFeatureWorkspace(workspaceWave.featureDirs, channel));
                 actorCompleted += 1;
                 reportProgress("actor", actorCompleted, wave.length, actorCompleted === wave.length ? "done" : "running", "waiting");
                 return { definition, channel, actor };
@@ -530,7 +655,7 @@ export class Orchestrator {
             await this.sessions.updateTaskStatus(task, "critic_running");
             const pairRunById = new Map();
             if (restoredWave) {
-                const restoredPairs = await Promise.all(actorRuns.map((actorRun) => this.loadCompletedFeaturePair(task, route.critic_engine, actorRun)));
+                const restoredPairs = await Promise.all(actorRuns.map((actorRun) => this.loadCompletedFeaturePair(task, requiredFeatureAssignment(assignments, actorRun.channel).critic_engine, actorRun)));
                 for (const pairRun of restoredPairs) {
                     if (pairRun) {
                         pairRunById.set(pairRun.definition.id, pairRun);
@@ -546,7 +671,7 @@ export class Orchestrator {
             }
             const freshPairRuns = await mapWithConcurrency(pendingCritics, concurrency, async (actorRun) => {
                 const reviewWorkspace = await workspaceManager.prepareFeatureReviewWorkspace(workspaceWave, actorRun.channel.id);
-                const critic = await this.runCritic(input, task, route.critic_engine, judge.dir, actorRun.actor.dir, workers, turn, actorRun.channel, true, reviewWorkspace);
+                const critic = await this.runCritic(input, task, requiredFeatureAssignment(assignments, actorRun.channel).critic_engine, judge.dir, actorRun.actor.dir, workers, turn, actorRun.channel, true, reviewWorkspace);
                 criticCompleted += 1;
                 reportProgress("critic", criticCompleted, actorRuns.length, "done", criticCompleted === actorRuns.length ? "done" : "running");
                 return { ...actorRun, critic };
@@ -562,30 +687,42 @@ export class Orchestrator {
                 return pairRun;
             });
             throwIfCancelled(input.signal);
-            const revisionRuns = [];
+            let finalPairs = pairRuns;
             const revisionFindingIds = new Map();
-            for (const pair of pairRuns) {
-                const review = await readTextIfExists(join(pair.critic.dir, "review.md"));
-                const decision = criticReviewDecision(review);
-                if (decision === "revision") {
-                    revisionFindingIds.set(pair.channel.id, await requireFeatureRevisionFindings(pair.channel));
-                    revisionRuns.push({ ...pair, review });
-                }
-                else if (decision !== "approved") {
-                    throw new Error(`Critic review for feature ${pair.channel.id} must include APPROVED or REVISION_REQUIRED.`);
+            let revisionRound = 0;
+            while (true) {
+                const revisionRuns = [];
+                for (const pair of finalPairs) {
+                    const review = await readTextIfExists(join(pair.critic.dir, "review.md"));
+                    const decision = criticReviewDecision(review);
+                    if (decision === "revision") {
+                        if (revisionRound >= this.config.orchestration.maxRevisionRounds) {
+                            throw new Error(`Critic still requires revision for ${pair.channel.id} after ${revisionRound} revision rounds.`);
+                        }
+                        const findingIds = await requireFeatureRevisionFindings(pair.channel);
+                        const accumulated = revisionFindingIds.get(pair.channel.id) ?? new Set();
+                        findingIds.forEach((id) => accumulated.add(id));
+                        revisionFindingIds.set(pair.channel.id, accumulated);
+                        revisionRuns.push({ ...pair, review });
+                    }
+                    else if (decision !== "approved") {
+                        throw new Error(`Critic review for feature ${pair.channel.id} must include APPROVED or REVISION_REQUIRED.`);
+                    }
+                    else {
+                        const accumulated = revisionFindingIds.get(pair.channel.id);
+                        await recordApprovedFindingResolution(pair.channel, accumulated ? [...accumulated] : [], {
+                            allowLegacyResolvedFindings: Boolean(input.retry) && !accumulated
+                        });
+                    }
                 }
-                else {
-                    await recordApprovedFindingResolution(pair.channel, [], {
-                        allowLegacyResolvedFindings: Boolean(input.retry)
-                    });
+                if (revisionRuns.length === 0) {
+                    break;
                 }
-            }
-            let finalPairs = pairRuns;
-            if (revisionRuns.length > 0) {
+                revisionRound += 1;
                 await this.sessions.updateTaskStatus(task, "revision_needed");
                 await Promise.all(revisionRuns.map(async ({ channel, critic }) => {
                     await updateFeatureStatus(channel, "revision_needed");
-                    await appendFeatureDialogue(channel, "critic.revision_requested", "critic", "Critic requested Actor revision.", {
+                    await appendFeatureDialogue(channel, "critic.revision_requested", "critic", `Critic requested Actor revision ${revisionRound}/${this.config.orchestration.maxRevisionRounds}.`, {
                         review: join(critic.dir, "review.md"),
                         findings: channel.criticFindingsPath
                     });
@@ -594,8 +731,8 @@ export class Orchestrator {
                 let revisionCompleted = 0;
                 reportProgress("revision", revisionCompleted, revisionRuns.length, "revision", "done");
                 const revisedActors = await mapWithConcurrency(revisionRuns, concurrency, async (pair) => {
-                    const actor = await this.runActor(input, task, route.actor_engine, judge.dir, workers, turn, pair.channel, buildRevisionRequest(pair.review, pair.channel), true, requiredFeatureWorkspace(workspaceWave.featureDirs, pair.channel));
-                    await requireActorFindingReplies(pair.channel, revisionFindingIds.get(pair.channel.id) ?? []);
+                    const actor = await this.runActor(input, task, requiredFeatureAssignment(assignments, pair.channel).actor_engine, judge.dir, workers, turn, pair.channel, buildRevisionRequest(pair.review, pair.channel, revisionRound, this.config.orchestration.maxRevisionRounds), true, requiredFeatureWorkspace(workspaceWave.featureDirs, pair.channel));
+                    await requireActorFindingReplies(pair.channel, [...(revisionFindingIds.get(pair.channel.id) ?? [])]);
                     revisionCompleted += 1;
                     reportProgress("revision", revisionCompleted, revisionRuns.length, "revision", "done");
                     return { ...pair, actor };
@@ -606,7 +743,7 @@ export class Orchestrator {
                 reportProgress("critic", recheckCompleted, revisedActors.length, "done", "rerunning");
                 const revisedPairs = await mapWithConcurrency(revisedActors, concurrency, async (pair) => {
                     const reviewWorkspace = await workspaceManager.prepareFeatureReviewWorkspace(workspaceWave, pair.channel.id);
-                    const critic = await this.runCritic(input, task, route.critic_engine, judge.dir, pair.actor.dir, workers, turn, pair.channel, true, reviewWorkspace);
+                    const critic = await this.runCritic(input, task, requiredFeatureAssignment(assignments, pair.channel).critic_engine, judge.dir, pair.actor.dir, workers, turn, pair.channel, true, reviewWorkspace);
                     recheckCompleted += 1;
                     reportProgress("critic", recheckCompleted, revisedActors.length, "done", "rerunning");
                     return {
@@ -617,14 +754,7 @@ export class Orchestrator {
                     };
                 });
                 const replacements = new Map(revisedPairs.map((pair) => [pair.definition.id, pair]));
-                finalPairs = pairRuns.map((pair) => replacements.get(pair.definition.id) ?? pair);
-                for (const pair of revisedPairs) {
-                    const review = await readTextIfExists(join(pair.critic.dir, "review.md"));
-                    if (criticReviewDecision(review) !== "approved") {
-                        throw new Error(`Critic did not approve feature ${pair.channel.id} after Actor revision.`);
-                    }
-                    await recordApprovedFindingResolution(pair.channel, revisionFindingIds.get(pair.channel.id) ?? []);
-                }
+                finalPairs = finalPairs.map((pair) => replacements.get(pair.definition.id) ?? pair);
                 throwIfCancelled(input.signal);
             }
             const waveSummaries = await allOrThrow(finalPairs.map(async (pair) => {
@@ -655,9 +785,14 @@ export class Orchestrator {
             await writeText(firstReviewPath, waveReview);
             await this.sessions.appendEvent(task, "feature.wave_reviewed", `Wave ${waveNumber}/${featureWaves.length} Critic decision: ${waveDecision}`);
             let waveRevised = false;
-            if (waveDecision === "revision") {
+            let waveRevisionRound = 0;
+            while (waveDecision === "revision") {
+                if (waveRevisionRound >= this.config.orchestration.maxRevisionRounds) {
+                    throw new Error(`Wave ${waveNumber}/${featureWaves.length} Critic still requires revision after ${waveRevisionRound} revision rounds. Live workspace was not changed.`);
+                }
+                waveRevisionRound += 1;
                 waveRevised = true;
-                await this.sessions.appendEvent(task, "feature.wave_revision_requested", `Wave ${waveNumber}/${featureWaves.length} Critic requested combined revision`);
+                await this.sessions.appendEvent(task, "feature.wave_revision_requested", `Wave ${waveNumber}/${featureWaves.length} Critic requested combined revision ${waveRevisionRound}/${this.config.orchestration.maxRevisionRounds}`);
                 await this.sessions.updateTaskStatus(task, "revision_needed");
                 await Promise.all(finalPairs.map(({ channel }) => updateFeatureStatus(channel, "revision_needed")));
                 reportProgress("revision", 0, 1, "revision", "done");
@@ -672,15 +807,13 @@ export class Orchestrator {
                 waveCritic = await this.runWaveCritic(input, task, route.critic_engine, judge.dir, workers, turn, verificationWorkspace, waveNumber, featureWaves.length, finalPairs.map(({ channel }) => channel.id), true);
                 waveReview = await readTextIfExists(join(waveCritic.dir, "review.md"));
                 waveDecision = criticReviewDecision(waveReview);
-                const secondReviewPath = join(workspaceWave.rootDir, "verification-review-02.md");
-                waveReviewPaths.push(secondReviewPath);
-                await writeText(secondReviewPath, waveReview);
-                await this.sessions.appendEvent(task, "feature.wave_reviewed", `Wave ${waveNumber}/${featureWaves.length} Critic recheck decision: ${waveDecision}`);
+                const reviewPath = join(workspaceWave.rootDir, `verification-review-${String(waveRevisionRound + 1).padStart(2, "0")}.md`);
+                waveReviewPaths.push(reviewPath);
+                await writeText(reviewPath, waveReview);
+                await this.sessions.appendEvent(task, "feature.wave_reviewed", `Wave ${waveNumber}/${featureWaves.length} Critic recheck ${waveRevisionRound}/${this.config.orchestration.maxRevisionRounds} decision: ${waveDecision}`);
             }
             if (waveDecision !== "approved") {
-                const detail = waveDecision === "revision"
-                    ? "still requires revision after the Wave Actor pass"
-                    : "did not include APPROVED or REVISION_REQUIRED";
+                const detail = "did not include APPROVED or REVISION_REQUIRED";
                 throw new Error(`Wave ${waveNumber}/${featureWaves.length} Critic ${detail}. Live workspace was not changed.`);
             }
             reportProgress("verification", 1, 1, "done", "done");
@@ -713,6 +846,7 @@ export class Orchestrator {
             changedPaths: [...changedPaths]
         });
         await writeText(join(turn.dir, "supervisor-summary.md"), `${summary}\n`);
+        await this.runFinalJudgeAcceptance(completionInput(input), task, turn, workers, route.judge_engine, judge, workspaceManager, [...changedPaths].sort());
         await this.sessions.updateTaskStatus(task, "done");
         input.onStatus?.({ taskId: task.id, judge: "done", actor: "done", critic: "done" });
         return {
@@ -723,6 +857,10 @@ export class Orchestrator {
         };
     }
     async runActorCriticPair(input, task, route, turn, workers, judge, feature) {
+        const assignment = await readFeatureAssignment(feature, {
+            actor: route.actor_engine,
+            critic: route.critic_engine
+        });
         const workspaceManager = new ParallelWorkspaceManager({
             workspaceRoot: input.cwd,
             taskDir: task.dir,
@@ -745,7 +883,7 @@ export class Orchestrator {
                 critic: "done",
                 featureProgress: { wave: 1, waves: 1, phase: "integration", completed: 1, total: 1 }
             });
-            return this.completeTask(task, turn, judge, this.workerFiles(task, taskWorkerId("actor", route.actor_engine, turn.turnId)), this.workerFiles(task, taskWorkerId("critic", route.critic_engine, turn.turnId)), feature, input, workers, await integratedWaveChangedPaths(workspaceRootDir));
+            return this.completeTask(task, turn, judge, this.workerFiles(task, taskWorkerId("actor", assignment.actor_engine, turn.turnId)), this.workerFiles(task, taskWorkerId("critic", assignment.critic_engine, turn.turnId)), feature, input, workers, await integratedWaveChangedPaths(workspaceRootDir), workspaceManager, route.judge_engine);
         }
         const restoredWave = input.retry ? await workspaceManager.restoreWave(workspaceInput) : null;
         const workspaceWave = restoredWave ?? await workspaceManager.prepareWave(workspaceInput);
@@ -756,7 +894,7 @@ export class Orchestrator {
         throwIfCancelled(input.signal);
         await this.sessions.updateTaskStatus(task, "actor_running");
         const restoredActor = restoredWave
-            ? await this.loadCompletedActor(task, route.actor_engine, feature, false)
+            ? await this.loadCompletedActor(task, assignment.actor_engine, feature, false)
             : null;
         if (restoredActor) {
             await this.sessions.appendEvent(task, "feature.wave_actor_checkpoints_reused", "Reused 1/1 completed Actor checkpoint in wave 1/1");
@@ -769,13 +907,13 @@ export class Orchestrator {
         });
         let actor = restoredActor;
         if (!actor) {
-            actor = await this.runActor(input, task, route.actor_engine, judge.dir, workers, turn, feature, undefined, false, workspaceDir, true);
+            actor = await this.runActor(input, task, assignment.actor_engine, judge.dir, workers, turn, feature, undefined, false, workspaceDir, true);
         }
         await updateFeatureStatus(feature, "actor_done");
         throwIfCancelled(input.signal);
         await this.sessions.updateTaskStatus(task, "critic_running");
         const restoredCritic = restoredActor
-            ? await this.loadCompletedCritic(task, route.critic_engine, feature, false)
+            ? await this.loadCompletedCritic(task, assignment.critic_engine, feature, false)
             : null;
         if (restoredCritic) {
             await this.sessions.appendEvent(task, "feature.wave_critic_checkpoints_reused", "Reused 1/1 completed Critic checkpoint in wave 1/1");
@@ -790,7 +928,7 @@ export class Orchestrator {
         let critic = restoredCritic;
         if (!critic) {
             reviewWorkspace = await workspaceManager.prepareFeatureReviewWorkspace(workspaceWave, feature.id);
-            critic = await this.runCritic(input, task, route.critic_engine, judge.dir, actor.dir, workers, turn, feature, false, reviewWorkspace, true);
+            critic = await this.runCritic(input, task, assignment.critic_engine, judge.dir, actor.dir, workers, turn, feature, false, reviewWorkspace, true);
         }
         await updateFeatureStatus(feature, "critic_done");
         throwIfCancelled(input.signal);
@@ -799,32 +937,46 @@ export class Orchestrator {
         if (decision === "missing") {
             throw new Error(`Critic review for ${feature.id} must include APPROVED or REVISION_REQUIRED.`);
         }
-        if (decision === "revision") {
+        const revisionFindingIds = new Set();
+        let revisionRound = 0;
+        while (decision === "revision") {
+            if (revisionRound >= this.config.orchestration.maxRevisionRounds) {
+                throw new Error(`Critic still requires revision for ${feature.id} after ${revisionRound} revision rounds.`);
+            }
+            revisionRound += 1;
             const findingIds = await requireFeatureRevisionFindings(feature);
+            findingIds.forEach((id) => revisionFindingIds.add(id));
             await this.sessions.updateTaskStatus(task, "revision_needed");
             await updateFeatureStatus(feature, "revision_needed");
-            await appendFeatureDialogue(feature, "critic.revision_requested", "critic", "Critic requested Actor revision.", {
+            await appendFeatureDialogue(feature, "critic.revision_requested", "critic", `Critic requested Actor revision ${revisionRound}/${this.config.orchestration.maxRevisionRounds}.`, {
                 review: join(critic.dir, "review.md"),
                 findings: feature.criticFindingsPath
             });
-            input.onStatus?.({ taskId: task.id, judge: "done", actor: "revision", critic: "done" });
+            input.onStatus?.({
+                taskId: task.id,
+                judge: "done",
+                actor: `revision ${revisionRound}/${this.config.orchestration.maxRevisionRounds}`,
+                critic: "done"
+            });
             await this.sessions.updateTaskStatus(task, "actor_running");
-            actor = await this.runActor(input, task, route.actor_engine, judge.dir, workers, turn, feature, buildRevisionRequest(review, feature), false, workspaceDir, true);
-            await requireActorFindingReplies(feature, findingIds);
+            actor = await this.runActor(input, task, assignment.actor_engine, judge.dir, workers, turn, feature, buildRevisionRequest(review, feature, revisionRound, this.config.orchestration.maxRevisionRounds), false, workspaceDir, true);
+            await requireActorFindingReplies(feature, [...revisionFindingIds]);
             await updateFeatureStatus(feature, "actor_done");
             throwIfCancelled(input.signal);
             reviewWorkspace = await workspaceManager.prepareFeatureReviewWorkspace(workspaceWave, feature.id);
             await this.sessions.updateTaskStatus(task, "critic_running");
             input.onStatus?.({ taskId: task.id, judge: "done", actor: "done", critic: "rerunning" });
-            critic = await this.runCritic(input, task, route.critic_engine, judge.dir, actor.dir, workers, turn, feature, false, reviewWorkspace, true);
+            critic = await this.runCritic(input, task, assignment.critic_engine, judge.dir, actor.dir, workers, turn, feature, false, reviewWorkspace, true);
             await updateFeatureStatus(feature, "critic_done");
             throwIfCancelled(input.signal);
             review = await readTextIfExists(`${critic.dir}/review.md`);
             decision = criticReviewDecision(review);
-            if (decision !== "approved") {
-                throw new Error(`Critic did not approve ${feature.id} after Actor revision.`);
+            if (decision === "missing") {
+                throw new Error(`Critic review for ${feature.id} must include APPROVED or REVISION_REQUIRED.`);
             }
-            await recordApprovedFindingResolution(feature, findingIds);
+        }
+        if (revisionFindingIds.size > 0) {
+            await recordApprovedFindingResolution(feature, [...revisionFindingIds]);
         }
         else {
             await recordApprovedFindingResolution(feature, [], {
@@ -849,9 +1001,9 @@ export class Orchestrator {
             critic: "done",
             featureProgress: { wave: 1, waves: 1, phase: "integration", completed: 1, total: 1 }
         });
-        return this.completeTask(task, turn, judge, actor, critic, feature, input, workers, integration.changedPaths);
+        return this.completeTask(task, turn, judge, actor, critic, feature, input, workers, integration.changedPaths, workspaceManager, route.judge_engine);
     }
-    async completeTask(task, turn, judge, actor, critic, feature, input, workers, changedPaths) {
+    async completeTask(task, turn, judge, actor, critic, feature, input, workers, changedPaths, workspaceManager, judgeEngine) {
         const summary = await buildSupervisorSummary({
             judgeDir: judge.dir,
             actorDir: actor.dir,
@@ -861,6 +1013,7 @@ export class Orchestrator {
             changedPaths
         });
         await writeText(join(turn.dir, "supervisor-summary.md"), `${summary}\n`);
+        await this.runFinalJudgeAcceptance(completionInput(input), task, turn, workers, judgeEngine, judge, workspaceManager, [...new Set(changedPaths)].sort());
         await writeFeatureDecision(feature, summary);
         await updateFeatureStatus(feature, "approved");
         await this.sessions.updateTaskStatus(task, "done");
@@ -874,11 +1027,18 @@ export class Orchestrator {
     }
     async failTask(task, features, input, error) {
         const featureCancellation = error instanceof FeatureRunCancelledError ? error : null;
+        const featurePause = error instanceof FeatureRunPausedError ? error : null;
         const cancelled = Boolean(featureCancellation) || isCancellation(error, input.signal);
-        const state = cancelled ? "cancelled" : "failed";
+        const state = featurePause ? "paused" : cancelled ? "cancelled" : "failed";
         const convergenceErrors = [];
         const featureUpdates = await Promise.allSettled(features.map(async (feature) => {
             if (!(await featureIsApproved(feature))) {
+                if (featurePause) {
+                    if (feature.id === featurePause.featureId) {
+                        await updateFeatureStatus(feature, "paused");
+                    }
+                    return;
+                }
                 const featureState = featureCancellation
                     ? feature.id === featureCancellation.featureId ? "cancelled" : "failed"
                     : state;
@@ -904,6 +1064,14 @@ export class Orchestrator {
                 convergenceErrors.push(eventError);
             }
         }
+        if (featurePause) {
+            try {
+                await this.sessions.appendEvent(task, "feature.paused", `Paused ${featurePause.featureId}; completed peer checkpoints preserved`);
+            }
+            catch (eventError) {
+                convergenceErrors.push(eventError);
+            }
+        }
         input.onStatus?.({ taskId: task.id });
         if (convergenceErrors.length > 0) {
             const details = convergenceErrors.map(errorMessage).join("; ");
@@ -912,6 +1080,9 @@ export class Orchestrator {
         if (featureCancellation) {
             throw featureCancellation;
         }
+        if (featurePause) {
+            throw featurePause;
+        }
         throw cancelled ? cancellationError() : error;
     }
     async routeRequest(request, workspace, signal, scope = "initial", onRouteStart, onRouteFallback, onRouteProgress) {
@@ -1164,8 +1335,107 @@ export class Orchestrator {
         ensureWorkerSuccess(result);
         return judge;
     }
+    async runFinalJudgeAcceptance(input, task, turn, workers, engine, judge, workspaceManager, changedPaths) {
+        const judgeReport = await this.validateJudgeSnapshot(turn);
+        if (judgeReport.state !== "valid") {
+            throw new Error(judgeValidationError(turn, judgeReport));
+        }
+        await writeJson(join(turn.dir, COMPLETION_CONTRACT_FILE), {
+            version: 1,
+            final_judge_required: true
+        });
+        const criterionIds = judgeReport.contract.acceptance.map((item) => item.id);
+        const persistedPath = join(turn.dir, FINAL_ACCEPTANCE_FILE);
+        const validationPath = join(turn.dir, FINAL_ACCEPTANCE_VALIDATION_FILE);
+        if (input.retry) {
+            const checkpoint = await readFinalJudgeAcceptance(persistedPath, criterionIds, changedPaths);
+            if (checkpoint?.report.state === "valid" && checkpoint.acceptance?.decision === "approved") {
+                await this.sessions.appendEvent(task, "judge.final_checkpoint_reused", `Reused approved Final Judge acceptance for turn ${turn.turnId}`);
+                return;
+            }
+        }
+        const verificationWorkspace = await workspaceManager.prepareFinalVerificationWorkspace(turn.turnId);
+        await this.sessions.updateTaskStatus(task, "verifying");
+        input.onStatus?.({ taskId: task.id, judge: "verifying", actor: "done", critic: "done" });
+        await this.sessions.appendEvent(task, "judge.final_started", `Final Judge started integration acceptance for ${criterionIds.length} criteria`);
+        const workerId = `judge-${engine}-final-${turn.turnId}`;
+        const featureTitle = finalJudgeTitle(turn.turnId);
+        const workerFiles = this.workerFiles(task, workerId);
+        await removeIfExists(join(workerFiles.dir, FINAL_ACCEPTANCE_FILE));
+        await removeIfExists(persistedPath);
+        await removeIfExists(validationPath);
+        const finalJudge = await this.sessions.initializeWorker(task, {
+            workerId,
+            featureTitle,
+            role: "judge",
+            engine,
+            preserveOutput: input.retry,
+            prompt: buildFinalJudgePrompt({
+                request: input.request,
+                taskDir: task.dir,
+                judgeDir: judge.dir,
+                workerDir: workerFiles.dir,
+                workspaceDir: verificationWorkspace,
+                supervisorSummaryPath: join(turn.dir, "supervisor-summary.md"),
+                expectedCriterionIds: criterionIds,
+                changedPaths,
+                turn: await this.promptTurnContext(task, turn),
+                role: this.config.roles.judge
+            })
+        });
+        this.recordWorker(input, workers, {
+            id: finalJudge.workerId,
+            role: "judge",
+            engine,
+            label: workerLabel("judge", engine, featureTitle),
+            logPath: finalJudge.outputLogPath,
+            statusPath: finalJudge.statusPath
+        });
+        const initialJudge = this.workerFiles(task, taskWorkerId("judge", engine, turn.turnId));
+        const result = await this.runWorkerWithNativeSession(engine, {
+            workerId: finalJudge.workerId,
+            featureTitle,
+            role: "judge",
+            engine,
+            cwd: verificationWorkspace,
+            enforceWorkspaceIsolation: true,
+            writableDirs: uniquePaths([finalJudge.dir, judge.dir, join(task.dir, "features"), turn.dir]),
+            filesDir: finalJudge.dir,
+            promptPath: finalJudge.promptPath,
+            outputLogPath: finalJudge.outputLogPath,
+            statusPath: finalJudge.statusPath,
+            prompt: await readTextIfExists(finalJudge.promptPath),
+            signal: input.signal
+        }, "task", initialJudge);
+        ensureWorkerSuccess(result);
+        throwIfCancelled(input.signal);
+        const workerAcceptancePath = join(finalJudge.dir, FINAL_ACCEPTANCE_FILE);
+        const raw = await readTextIfExists(workerAcceptancePath);
+        if (raw.trim()) {
+            await writeText(persistedPath, raw);
+        }
+        const validated = await readFinalJudgeAcceptance(workerAcceptancePath, criterionIds, changedPaths);
+        const report = validated?.report ?? {
+            version: 1,
+            state: "invalid",
+            decision: "unknown",
+            issues: [`${FINAL_ACCEPTANCE_FILE} is missing or empty`]
+        };
+        await writeJson(validationPath, report);
+        if (report.state !== "valid") {
+            await this.sessions.appendEvent(task, "judge.final_invalid", report.issues.join("; "));
+            throw new Error(`Final Judge acceptance is invalid: ${report.issues.join("; ")}`);
+        }
+        if (validated?.acceptance?.decision !== "approved") {
+            await this.sessions.appendEvent(task, "judge.final_rejected", validated?.acceptance?.summary ?? "Final Judge rejected integration");
+            throw new Error(`Final Judge rejected integration: ${validated?.acceptance?.summary ?? "no summary"}`);
+        }
+        await this.sessions.appendEvent(task, "judge.final_approved", `Final Judge approved ${criterionIds.length} acceptance criteria`);
+        input.onStatus?.({ taskId: task.id, judge: "done", actor: "done", critic: "done" });
+    }
     async runActor(input, task, engine, judgeDir, workers, turn, feature, revision, featureScoped = false, workspaceDir = input.cwd, isolatedWorkspace = featureScoped) {
         const workerId = taskWorkerId("actor", engine, turn.turnId, featureScoped ? feature.id : undefined);
+        const workerFiles = this.workerFiles(task, workerId);
         const actor = await this.sessions.initializeWorker(task, {
             workerId,
             ...(featureScoped ? { featureId: feature.id } : {}),
@@ -1177,6 +1447,7 @@ export class Orchestrator {
                 request: input.request,
                 taskDir: task.dir,
                 judgeDir,
+                workerDir: workerFiles.dir,
                 turn: await this.promptTurnContext(task, turn),
                 feature: featurePromptContext(feature),
                 ...(isolatedWorkspace ? { workspaceDir } : {}),
@@ -1224,6 +1495,7 @@ export class Orchestrator {
     }
     async runCritic(input, task, engine, judgeDir, actorDir, workers, turn, feature, featureScoped = false, workspaceDir = input.cwd, isolatedWorkspace = featureScoped) {
         const workerId = taskWorkerId("critic", engine, turn.turnId, featureScoped ? feature.id : undefined);
+        const workerFiles = this.workerFiles(task, workerId);
         const critic = await this.sessions.initializeWorker(task, {
             workerId,
             ...(featureScoped ? { featureId: feature.id } : {}),
@@ -1235,6 +1507,7 @@ export class Orchestrator {
                 request: input.request,
                 taskDir: task.dir,
                 judgeDir,
+                workerDir: workerFiles.dir,
                 actorDir,
                 turn: await this.promptTurnContext(task, turn),
                 feature: featurePromptContext(feature),
@@ -1272,6 +1545,9 @@ export class Orchestrator {
             ? undefined
             : await this.previousTurnWorker(task, "critic", engine, turn.turnId));
         ensureWorkerSuccess(result);
+        if (isolatedWorkspace) {
+            await recoverWorkerFileFromWorkspace(join(workspaceDir, "review.md"), join(critic.dir, "review.md"));
+        }
         await appendFeatureDialogue(feature, "critic.completed", "critic", "Critic completed feature review.", {
             review: join(critic.dir, "review.md"),
             findings: feature.criticFindingsPath
@@ -1397,6 +1673,7 @@ export class Orchestrator {
         const active = {
             controller,
             cancelRequested: false,
+            pauseRequested: false,
             role
         };
         const abortFromParent = () => controller.abort();
@@ -1413,6 +1690,9 @@ export class Orchestrator {
                 ...spec,
                 signal: controller.signal
             }, "task", resumeFrom);
+            if (active.pauseRequested) {
+                throw new FeatureRunPausedError(feature.id);
+            }
             if (active.cancelRequested) {
                 throw new FeatureRunCancelledError(feature.id);
             }
@@ -1421,6 +1701,9 @@ export class Orchestrator {
             return result;
         }
         catch (error) {
+            if (active.pauseRequested && !(error instanceof FeatureRunPausedError)) {
+                throw new FeatureRunPausedError(feature.id);
+            }
             if (active.cancelRequested && !(error instanceof FeatureRunCancelledError)) {
                 throw new FeatureRunCancelledError(feature.id);
             }
@@ -1471,7 +1754,7 @@ export class Orchestrator {
         return adapter.run({
             ...spec,
             nativeSession: existing,
-            nativeSessionConfig: this.config.workers[engine].nativeSession,
+            nativeSessionConfig: workerProvider(this.config, engine).config.nativeSession,
             onNativeSession: async (sessionId) => {
                 const now = new Date().toISOString();
                 const previous = await this.sessions.readNativeSession(workerFiles);
@@ -1735,6 +2018,11 @@ function cancellationError() {
     error.name = "AbortError";
     return error;
 }
+function completionInput(input) {
+    const detached = { ...input };
+    delete detached.signal;
+    return detached;
+}
 function isCancellation(error, signal) {
     return Boolean(signal?.aborted) || (error instanceof Error && error.name === "AbortError");
 }
@@ -1771,8 +2059,10 @@ function summarizeRetirementReason(reason) {
     const summary = contextLine ?? lines.at(-1) ?? "Native session retired";
     return summary.length > 240 ? `${summary.slice(0, 237)}...` : summary;
 }
-function buildRevisionRequest(review, feature) {
+function buildRevisionRequest(review, feature, round = 1, maxRounds = 1) {
     return [
+        `Revision round: ${round}/${maxRounds}`,
+        "",
         review.trim(),
         "",
         "Feature mailbox:",
@@ -1791,12 +2081,38 @@ function criticReviewDecision(review) {
     }
     return "missing";
 }
+async function readFinalJudgeAcceptance(path, criterionIds, changedPaths) {
+    const raw = await readTextIfExists(path);
+    if (!raw.trim()) {
+        return null;
+    }
+    try {
+        return validateFinalJudgeAcceptance(JSON.parse(raw), criterionIds, changedPaths);
+    }
+    catch (error) {
+        return {
+            acceptance: null,
+            report: {
+                version: 1,
+                state: "invalid",
+                decision: "unknown",
+                issues: [`${FINAL_ACCEPTANCE_FILE} is not valid JSON: ${errorMessage(error)}`]
+            }
+        };
+    }
+}
 async function mirrorWorkerFileToFeature(sourcePath, targetPath) {
     const content = await readTextIfExists(sourcePath);
     if (content.trim()) {
         await writeText(targetPath, content);
     }
 }
+async function recoverWorkerFileFromWorkspace(sourcePath, targetPath) {
+    if ((await readTextIfExists(targetPath)).trim()) {
+        return;
+    }
+    await mirrorWorkerFileToFeature(sourcePath, targetPath);
+}
 function extractMainResponse(outputLog) {
     return outputLog
         .split("\n")
@@ -1820,6 +2136,11 @@ function taskWorkerLabel(role, engine, turnId) {
         ? workerLabel(role, engine)
         : workerLabel(role, engine, `Turn ${Number(turnId)}`);
 }
+function finalJudgeTitle(turnId) {
+    return turnId === "0001"
+        ? "Final acceptance"
+        : `Turn ${Number(turnId)} final`;
+}
 function workerLabelForStatus(status) {
     const feature = status.feature_title ?? status.feature_id;
     if (feature) {
@@ -1845,6 +2166,11 @@ function capitalize(value) {
 function workerRoleOrder(role) {
     return ["main", "judge", "actor", "critic"].indexOf(role);
 }
+function workerStageOrder(worker) {
+    return worker.role === "judge" && /-final-\d{4,}$/.test(worker.id)
+        ? 4
+        : workerRoleOrder(worker.role);
+}
 function workerTurnOrder(worker) {
     const featureTurn = worker.featureId?.match(/^(\d{4,})(?:-|$)/)?.[1];
     const waveTurn = worker.id.match(/-wave-(\d{4,})-/)?.[1];
@@ -1870,9 +2196,19 @@ function requiredChannel(channels, definition) {
     }
     return channel;
 }
+function requiredFeatureAssignment(assignments, channel) {
+    const assignment = assignments.get(channel.id);
+    if (!assignment) {
+        throw new Error(`Feature engine assignment missing: ${channel.id}`);
+    }
+    return assignment;
+}
 function featureRunKey(taskId, featureId) {
     return `${taskId}\u0000${featureId}`;
 }
+function featureIdIsSafe(featureId) {
+    return /^[a-z0-9][a-z0-9-]{0,95}$/.test(featureId);
+}
 function requiredFeatureWorkspace(featureDirs, channel) {
     const workspace = featureDirs.get(channel.id);
     if (!workspace) {