@cat-factory/orchestration 0.129.7 → 0.129.10

package/dist/modules/execution/RunDispatcher.js

@@ -1,4 +1,4 @@
-import { ConflictError, DEFAULT_RISK_POLICY, failureKindFromHarnessCause, FIXER_AGENT_KIND, getErrorMessage, isAsyncAgentExecutor, NotFoundError, parseLocalModelId, recordGateAttempt, RunContendedError, sameSubtasks, } from '@cat-factory/kernel';
+import { ConflictError, DEFAULT_RISK_POLICY, failureKindFromHarnessCause, getErrorMessage, isAsyncAgentExecutor, NotFoundError, parseLocalModelId, recordGateAttempt, RunContendedError, sameSubtasks, } from '@cat-factory/kernel';
 import { parseBlueprintService, parseSpecDoc } from '@cat-factory/contracts';
 import { commitInitiativeTracker, FORK_PROPOSER_KIND, PR_REVIEWER_KIND } from '@cat-factory/agents';
 import { isDeployStep } from '@cat-factory/integrations';
@@ -15,7 +15,8 @@ import { MergeResolver } from './MergeResolver.js';
 import { ReviewGateController } from './ReviewGateController.js';
 import { ForkDecisionController } from './ForkDecisionController.js';
 import { PrReviewController } from './PrReviewController.js';
-import { buildPrReviewPost, initialPrReviewState, renderPrReviewFixerFeedback, } from './prReview.logic.js';
+import { initialPrReviewState } from './prReview.logic.js';
+import { PrReviewResolutionController } from './PrReviewResolutionController.js';
 import { DEFAULT_FORK_MAX_CHAT_TURNS, resolveForkTriState, shouldProposeForkAuto, } from './forkDecision.logic.js';
 import { RunStateMachine } from './RunStateMachine.js';
 import { StepGraph } from './StepGraph.js';
@@ -24,19 +25,6 @@ import { RalphController } from './RalphController.js';
 import { VisualConfirmationController } from './VisualConfirmationController.js';
 import {} from './step-handler-registry.js';
 import { buildStepCompletionInterceptors as buildStepCompletionInterceptorsImpl, buildStepHandlerRegistry as buildStepHandlerRegistryImpl, buildStepResolverRegistry as buildStepResolverRegistryImpl, } from './dispatcher-registries.js';
-/**
- * The PR number a `review` task targets: the explicit `prNumber` field wins, else parse it from
- * the `prUrl` (`…/pull/42` on GitHub, `…/merge_requests/42` on GitLab). Undefined when neither
- * yields one — the PR-review `fix`/`post` resolutions then report the PR unresolvable.
- */
-function reviewPrNumber(block) {
-    const fields = block?.taskTypeFields;
-    if (typeof fields?.prNumber === 'number')
-        return fields.prNumber;
-    const url = fields?.prUrl?.trim();
-    const match = url ? /\/(?:pull|merge_requests)\/(\d+)/.exec(url) : null;
-    return match ? Number(match[1]) : undefined;
-}
 /**
  * The per-step dispatch + completion spine of the execution engine. It owns the four
  * registries (step handlers, completion interceptors, post-completion / terminal resolvers,
@@ -104,6 +92,8 @@ export class RunDispatcher {
      */
     deployer;
     repoOps;
+    /** Driver-side PR deep-review resolution (`fix` / `post`), extracted as a cohesive collaborator. */
+    prReviewResolution;
     /**
      * The Follow-up companion gate (the future-looking Coder's streamed items, the
      * park-until-decided gate, and the human-action API), extracted to
@@ -198,6 +188,13 @@ export class RunDispatcher {
             resolveRunRepoContext: deps.resolveRunRepoContext,
             issueWriteback: deps.issueWriteback,
         });
+        this.prReviewResolution = new PrReviewResolutionController({
+            runStateMachine: deps.runStateMachine,
+            resolveRunRepoContext: deps.resolveRunRepoContext,
+            runInitiatorScope: this.runInitiatorScope,
+            recordStepResult: (ws, instance, step, isFinalStep, result) => this.recordStepResult(ws, instance, step, isFinalStep, result),
+            handleAgentStep: (ctx, dispatchKind, augment) => this.handleAgentStep(ctx, dispatchKind, augment),
+        });
         // Assemble the seam the extracted dispatch-registry builders close over: the collaborators
         // above + bound call-backs into this dispatcher's completion / gate / phase methods, so the
         // built-ins resolve everything at call time exactly as the former inline closures did.
@@ -527,42 +524,7 @@ export class RunDispatcher {
             agentKind: step.agentKind,
         });
         if (update.state === 'running') {
-            // A successful poll proves the container is up, so the cold-boot phase is over
-            // (defensive: a replay may have left the flag set). Surface live subtask progress
-            // (e.g. 3/8 todos done) without advancing the step. Only persist + emit when something
-            // actually changed so an idle poll doesn't churn storage or the event stream.
-            //
-            // Fold the poll's delta onto a target instance via {@link applyRunningFold}. The captured
-            // `update` is the source, so re-applying on a freshly-reloaded instance is idempotent for
-            // the set-to-latest folds AND correct for the APPEND fold: the harness follow-up buffer is
-            // drain-on-read (`runner.ts`), so those streamed items exist ONLY on this `update` — abort-
-            // and-redrive would lose them, whereas re-applying under `mutateInstance` (which reloads a
-            // clean base each attempt) preserves them.
-            const foldCtx = { jobId: step.jobId, update, workspaceId };
-            // Cheap pre-check against the loaded snapshot: skip the write entirely on an idle poll
-            // (the common case). The mutation is discarded — the authoritative write re-applies the
-            // same fold on fresh state under CAS below.
-            if (await this.applyRunningFold(instance, foldCtx)) {
-                try {
-                    const persisted = await this.runStateMachine.mutateInstance(workspaceId, executionId, async (fresh) => {
-                        await this.applyRunningFold(fresh, foldCtx);
-                    });
-                    // Progress-only fold (subtask ticks / streamed follow-ups): skip the per-run
-                    // LLM-metrics GROUP BY so a live container's poll cadence doesn't re-aggregate
-                    // the run on every tick. The rollup refreshes on the step-boundary/terminal emit.
-                    await this.runStateMachine.emitInstance(workspaceId, persisted, { rollUpMetrics: false });
-                }
-                catch (error) {
-                    // The run was cancelled/removed mid-poll (`NotFoundError`) or stayed hot-contended
-                    // past the retry budget (`ConflictError`) — re-drive on fresh state rather than
-                    // failing the run; the next entry no-ops on a gone/terminal run.
-                    if (error instanceof NotFoundError || error instanceof ConflictError) {
-                        throw new RunContendedError(executionId);
-                    }
-                    throw error;
-                }
-            }
-            return { kind: 'awaiting_job', jobId: step.jobId, stepIndex: instance.currentStep };
+            return this.handleRunningPoll(workspaceId, executionId, instance, update, step.jobId);
         }
         // A gate whose helper INVESTIGATES instead of fixing (post-release-health → on-call)
         // declares a `resolveHelperCompletion` hook on its definition. When such a helper's job
@@ -571,34 +533,9 @@ export class RunDispatcher {
         // budget) and finish the gate step with the output it returns. The gate raises its own
         // `release_regression` notification + enriches any open incident inside the hook (from the
         // signals stashed at escalation); the run then completes for a human to act out-of-band.
-        const completionGate = this.gateFor(step.agentKind);
-        if (completionGate?.resolveHelperCompletion &&
-            step.gate?.phase === 'working' &&
-            (update.state === 'done' || update.state === 'failed')) {
-            const block = await this.blockRepository.get(workspaceId, instance.blockId);
-            step.jobId = undefined;
-            step.subtasks = undefined;
-            if (!block)
-                return { kind: 'noop' };
-            const isFinalStep = instance.currentStep === instance.steps.length - 1;
-            const jobResult = update.state === 'done'
-                ? { state: 'done', result: update.result }
-                : { state: 'failed', error: update.error ?? null };
-            const resolution = await completionGate.resolveHelperCompletion({
-                workspaceId,
-                instance,
-                block,
-                step,
-                result: jobResult,
-            });
-            // Preserve the done-result's fields (usage metering etc.) while recording the gate's
-            // resolved output; a failed investigation has no result to carry.
-            const base = update.state === 'done' ? update.result : { output: '' };
-            return this.recordStepResult(workspaceId, instance, step, isFinalStep, {
-                ...base,
-                output: resolution.output,
-            });
-        }
+        const investigated = await this.resolveInvestigateHelperCompletion(workspaceId, instance, step, update);
+        if (investigated)
+            return investigated;
         // A polling gate step's in-flight job is its helper agent (ci-fixer /
         // conflict-resolver), NOT the step's own work: when it finishes (or fails) we
         // don't record a result or advance — we drop the handle, return the gate to
@@ -702,6 +639,81 @@ export class RunDispatcher {
         step.jobId = undefined;
         return this.recordStepResult(workspaceId, instance, step, isFinalStep, update.result);
     }
+    /**
+     * Handle a `running` poll: a successful poll proves the container is up, so surface live subtask
+     * progress (e.g. 3/8 todos) without advancing the step. Only persist + emit when something
+     * actually changed so an idle poll doesn't churn storage or the event stream. Folds the poll's
+     * delta via {@link applyRunningFold} — a cheap pre-check against the loaded snapshot, then the
+     * authoritative re-apply on fresh state under CAS (idempotent for the set-to-latest folds and
+     * correct for the drain-on-read follow-up append). Split from {@link pollAgentJobInner} to stay
+     * under the statement ceiling.
+     */
+    async handleRunningPoll(workspaceId, executionId, instance, update, jobId) {
+        const foldCtx = { jobId, update, workspaceId };
+        // Cheap pre-check against the loaded snapshot: skip the write entirely on an idle poll
+        // (the common case). The mutation is discarded — the authoritative write re-applies the
+        // same fold on fresh state under CAS below.
+        if (await this.applyRunningFold(instance, foldCtx)) {
+            try {
+                const persisted = await this.runStateMachine.mutateInstance(workspaceId, executionId, async (fresh) => {
+                    await this.applyRunningFold(fresh, foldCtx);
+                });
+                // Progress-only fold (subtask ticks / streamed follow-ups): skip the per-run
+                // LLM-metrics GROUP BY so a live container's poll cadence doesn't re-aggregate
+                // the run on every tick. The rollup refreshes on the step-boundary/terminal emit.
+                await this.runStateMachine.emitInstance(workspaceId, persisted, { rollUpMetrics: false });
+            }
+            catch (error) {
+                // The run was cancelled/removed mid-poll (`NotFoundError`) or stayed hot-contended
+                // past the retry budget (`ConflictError`) — re-drive on fresh state rather than
+                // failing the run; the next entry no-ops on a gone/terminal run.
+                if (error instanceof NotFoundError || error instanceof ConflictError) {
+                    throw new RunContendedError(executionId);
+                }
+                throw error;
+            }
+        }
+        return { kind: 'awaiting_job', jobId, stepIndex: instance.currentStep };
+    }
+    /**
+     * A gate whose helper INVESTIGATES instead of fixing (post-release-health → on-call) declares a
+     * `resolveHelperCompletion` hook. When such a helper's job settles — done OR failed — call the
+     * hook INSTEAD of re-probing the precheck (re-probing an investigate-don't-fix helper would just
+     * regress again and burn the budget) and finish the gate step with the output it returns. Returns
+     * the resulting {@link AdvanceResult}, or `null` when this branch doesn't apply (the caller falls
+     * through to the re-probe / other completion paths).
+     */
+    async resolveInvestigateHelperCompletion(workspaceId, instance, step, update) {
+        const completionGate = this.gateFor(step.agentKind);
+        if (completionGate?.resolveHelperCompletion &&
+            step.gate?.phase === 'working' &&
+            (update.state === 'done' || update.state === 'failed')) {
+            const block = await this.blockRepository.get(workspaceId, instance.blockId);
+            step.jobId = undefined;
+            step.subtasks = undefined;
+            if (!block)
+                return { kind: 'noop' };
+            const isFinalStep = instance.currentStep === instance.steps.length - 1;
+            const jobResult = update.state === 'done'
+                ? { state: 'done', result: update.result }
+                : { state: 'failed', error: update.error ?? null };
+            const resolution = await completionGate.resolveHelperCompletion({
+                workspaceId,
+                instance,
+                block,
+                step,
+                result: jobResult,
+            });
+            // Preserve the done-result's fields (usage metering etc.) while recording the gate's
+            // resolved output; a failed investigation has no result to carry.
+            const base = update.state === 'done' ? update.result : { output: '' };
+            return this.recordStepResult(workspaceId, instance, step, isFinalStep, {
+                ...base,
+                output: resolution.output,
+            });
+        }
+        return null;
+    }
     /**
      * Fold a running poll's container signals into `step.container`: a successful poll
      * proves the container is `up`, and the harness's live phase (clone / agent / push)
@@ -1049,12 +1061,7 @@ export class RunDispatcher {
                 options: [...result.decision.options],
                 chosen: null,
             };
-            this.stepGraph.pauseStepForInput(step);
-            instance.status = 'blocked';
-            await this.runStateMachine.updateBlockProgress(workspaceId, instance, 'blocked');
-            await this.runStateMachine.casPersist(workspaceId, instance);
-            await this.runStateMachine.emitInstance(workspaceId, instance);
-            return { kind: 'awaiting_decision', decisionId: step.decision.id };
+            return this.parkStepAwaitingInput(workspaceId, instance, step, step.decision.id);
         }
         // Completion-path interceptors short-circuit before the normal finish/advance for the
         // few kinds whose verdict drives run flow: a container-backed companion applies its
@@ -1095,30 +1102,7 @@ export class RunDispatcher {
         // (service-connections phase 3) additionally reports the PRs it opened in the
         // connected involved-service repos; record them beside the own-service PR (they may
         // even arrive when the own service was a no-op and only a peer changed).
-        if (result.pullRequest || result.peerPullRequests?.length) {
-            // Read the block before the update so we can tell whether this PR is newly
-            // opened (vs. the same PR re-reported by a re-run/retry of the coder step).
-            const priorBlock = this.issueWriteback
-                ? await this.blockRepository.get(workspaceId, instance.blockId)
-                : null;
-            await this.blockRepository.update(workspaceId, instance.blockId, {
-                ...(result.pullRequest ? { pullRequest: result.pullRequest } : {}),
-                ...(result.peerPullRequests?.length ? { peerPullRequests: result.peerPullRequests } : {}),
-            });
-            // Best-effort writeback: comment on the task's linked tracker issue(s) that a
-            // PR opened. Only for the OWN-service PR, and only when it is newly recorded — a
-            // retry that re-reports the same PR must not re-comment (the tracker comment is not
-            // idempotent). Gated inside the provider by the workspace setting + per-task
-            // override; fire-and-forget so a tracker outage never fails the run.
-            if (this.issueWriteback &&
-                priorBlock &&
-                result.pullRequest &&
-                priorBlock.pullRequest?.url !== result.pullRequest.url) {
-                await this.issueWriteback
-                    .onPullRequestOpened(workspaceId, priorBlock, result.pullRequest)
-                    .catch(() => { });
-            }
-        }
+        await this.recordOpenedPullRequests(workspaceId, instance, result);
         // Run any POST-COMPLETION resolver registered for this step kind (blueprint/spec
         // ingestion, task-estimate persistence). It reshapes the agent's structured result into
         // domain state and may replace `step.output` (the estimator's readable summary). Its
@@ -1126,19 +1110,7 @@ export class RunDispatcher {
         // reviewable-output rendering and the follow-up/approval gates read `step.output`, so it
         // sits exactly where the old inline ingestion branches did. See
         // {@link buildStepResolverRegistry} and {@link StepCompletionResolver.phase}.
-        const postCompletionResolver = this.stepResolverFor(step.agentKind);
-        if (postCompletionResolver?.phase === 'post-completion' &&
-            (postCompletionResolver.applies?.(result) ?? true)) {
-            const resolution = await postCompletionResolver.resolve({
-                workspaceId,
-                instance,
-                step,
-                result,
-                isFinalStep,
-            });
-            if (resolution?.output !== undefined)
-                step.output = resolution.output;
-        }
+        await this.applyPostCompletionResolver(workspaceId, instance, step, result, isFinalStep);
         // A producer that emits a STRUCTURED ARTIFACT (the spec doc, the blueprint tree, …)
         // returns its raw Pi transcript summary as `result.output` — useless for review.
         // Replace the step's reviewable output with a rendering of the artifact ITSELF, so
@@ -1173,12 +1145,7 @@ export class RunDispatcher {
                 status: 'pending',
                 proposal: step.output,
             };
-            this.stepGraph.pauseStepForInput(step);
-            instance.status = 'blocked';
-            await this.runStateMachine.updateBlockProgress(workspaceId, instance, 'blocked');
-            await this.runStateMachine.casPersist(workspaceId, instance);
-            await this.runStateMachine.emitInstance(workspaceId, instance);
-            return { kind: 'awaiting_decision', decisionId: step.approval.id };
+            return this.parkStepAwaitingInput(workspaceId, instance, step, step.approval.id);
         }
         // Persist the agent's reported confidence whenever a step reports it, for board
         // transparency. Position-independent: it must NOT be tied to the final step, since a
@@ -1194,23 +1161,7 @@ export class RunDispatcher {
         // — so inserting a later step (post-release-health) can't silently disable it. A
         // resolver that owns the block's terminal status (the merger sets `done`/`pr_ready`)
         // tells `finalizeBlock` to leave it alone.
-        const resolver = this.stepResolverFor(step.agentKind);
-        let resolverOwnsTerminalStatus = false;
-        if (resolver &&
-            (resolver.phase ?? 'terminal') === 'terminal' &&
-            (resolver.applies?.(result) ?? true)) {
-            const resolution = await resolver.resolve({
-                workspaceId,
-                instance,
-                step,
-                result,
-                isFinalStep,
-            });
-            if (resolution?.output !== undefined)
-                step.output = resolution.output;
-            if (resolution?.ownsTerminalStatus)
-                resolverOwnsTerminalStatus = true;
-        }
+        const resolverOwnsTerminalStatus = await this.applyTerminalStepResolver(workspaceId, instance, step, result, isFinalStep);
         // A registered custom kind's POST-ops run deterministic backend repo work from the
         // agent's structured result (coerce its JSON, render artifact files, commit them via
         // the checkout-free RepoFiles port — the blueprint/spec rendering that used to live in
@@ -1251,6 +1202,92 @@ export class RunDispatcher {
         await this.runStateMachine.emitInstance(workspaceId, instance);
         return { kind: 'continue' };
     }
+    /**
+     * Park a step on the durable decision-wait: pause it for input, flip the run + block to
+     * `blocked`, persist under CAS, emit, and report `awaiting_decision` keyed by `decisionId`.
+     * Shared by the raised-decision and human-approval branches of {@link recordStepResult}.
+     */
+    async parkStepAwaitingInput(workspaceId, instance, step, decisionId) {
+        this.stepGraph.pauseStepForInput(step);
+        instance.status = 'blocked';
+        await this.runStateMachine.updateBlockProgress(workspaceId, instance, 'blocked');
+        await this.runStateMachine.casPersist(workspaceId, instance);
+        await this.runStateMachine.emitInstance(workspaceId, instance);
+        return { kind: 'awaiting_decision', decisionId };
+    }
+    /**
+     * Record any PR(s) the step opened onto the block (its own-service PR + any peer-service PRs),
+     * and best-effort write back to the task's linked tracker issue(s) when the own-service PR is
+     * NEWLY opened (a retry that re-reports the same PR must not re-comment). Split from
+     * {@link recordStepResult} to keep it under the statement ceiling; a no-op when no PR was opened.
+     */
+    async recordOpenedPullRequests(workspaceId, instance, result) {
+        if (!(result.pullRequest || result.peerPullRequests?.length))
+            return;
+        // Read the block before the update so we can tell whether this PR is newly
+        // opened (vs. the same PR re-reported by a re-run/retry of the coder step).
+        const priorBlock = this.issueWriteback
+            ? await this.blockRepository.get(workspaceId, instance.blockId)
+            : null;
+        await this.blockRepository.update(workspaceId, instance.blockId, {
+            ...(result.pullRequest ? { pullRequest: result.pullRequest } : {}),
+            ...(result.peerPullRequests?.length ? { peerPullRequests: result.peerPullRequests } : {}),
+        });
+        // Best-effort writeback: comment on the task's linked tracker issue(s) that a
+        // PR opened. Only for the OWN-service PR, and only when it is newly recorded — a
+        // retry that re-reports the same PR must not re-comment (the tracker comment is not
+        // idempotent). Gated inside the provider by the workspace setting + per-task
+        // override; fire-and-forget so a tracker outage never fails the run.
+        if (this.issueWriteback &&
+            priorBlock &&
+            result.pullRequest &&
+            priorBlock.pullRequest?.url !== result.pullRequest.url) {
+            await this.issueWriteback
+                .onPullRequestOpened(workspaceId, priorBlock, result.pullRequest)
+                .catch(() => { });
+        }
+    }
+    /**
+     * Run any POST-COMPLETION resolver registered for this step kind (blueprint/spec ingestion,
+     * task-estimate persistence). It reshapes the agent's structured result into domain state and may
+     * replace `step.output`. A no-op when no post-completion resolver applies. See
+     * {@link buildStepResolverRegistry} and {@link StepCompletionResolver.phase}.
+     */
+    async applyPostCompletionResolver(workspaceId, instance, step, result, isFinalStep) {
+        const postCompletionResolver = this.stepResolverFor(step.agentKind);
+        if (postCompletionResolver?.phase !== 'post-completion' ||
+            !(postCompletionResolver.applies?.(result) ?? true)) {
+            return;
+        }
+        const resolution = await postCompletionResolver.resolve({
+            workspaceId,
+            instance,
+            step,
+            result,
+            isFinalStep,
+        });
+        if (resolution?.output !== undefined)
+            step.output = resolution.output;
+    }
+    /**
+     * Run any DETERMINISTIC terminal-phase resolver for this step kind (e.g. the merger performs the
+     * real GitHub merge with backend-held credentials), mutating `step.output` when it reshapes it.
+     * Position-independent: it fires whenever the step finishes, not only when it's last. Returns
+     * whether the resolver OWNS the block's terminal status (the merger sets `done`/`pr_ready`), so
+     * the advance/finalize path leaves that status alone rather than clobbering it to `in_progress`.
+     */
+    async applyTerminalStepResolver(workspaceId, instance, step, result, isFinalStep) {
+        const resolver = this.stepResolverFor(step.agentKind);
+        if (!resolver ||
+            (resolver.phase ?? 'terminal') !== 'terminal' ||
+            !(resolver.applies?.(result) ?? true)) {
+            return false;
+        }
+        const resolution = await resolver.resolve({ workspaceId, instance, step, result, isFinalStep });
+        if (resolution?.output !== undefined)
+            step.output = resolution.output;
+        return resolution?.ownsTerminalStatus ?? false;
+    }
     /**
      * File a tracking issue/ticket for a `tracker` step from the preceding `analysis`
      * output. Non-LLM and best-effort: when no provider is wired or none is configured
@@ -1763,120 +1800,13 @@ export class RunDispatcher {
         return this.handleAgentStep(ctx, FORK_PROPOSER_KIND);
     }
     /**
-     * Drive a re-armed PR-review step's RESOLUTION (PR 3). The human resolved a parked review with
-     * `fix` or `post`; {@link PrReviewController.resolve} re-armed this step and woke the driver.
-     * - `fixing`: dispatch the Fixer against the reviewed PR's head branch with the selected
-     *   findings folded in (parks on the job; its completion marks the review `done`).
-     * - `posting`: publish the selected findings as inline PR review comments, then finish the step.
-     */
-    async handlePrReviewResolution(ctx) {
-        const { step } = ctx;
-        if (step.prReview?.status === 'posting')
-            return this.postPrReview(ctx);
-        return this.dispatchPrReviewFixer(ctx);
-    }
-    /**
-     * Dispatch the Fixer for a PR-review `fix` resolution. A `review` task carries no own work
-     * branch — it reviews an EXISTING PR — so resolve the PR's head branch (via the checkout-free
-     * `RepoFiles`) and point the Fixer's clone/push at it: fold a synthetic `pullRequest` + an
-     * apriori WORKING branch into the dispatch context so the shared `container-coding` +
-     * `clone:{branch:'pr'}` fixer body clones + pushes that branch (no new PR), and hand it the
-     * selected findings as a prior output (the same injection point the gate helpers use). Fails
-     * the run loudly when the PR branch can't be resolved (nothing to push to) rather than pushing
-     * blind. On a replay (jobId already set) it re-attaches without re-resolving.
+     * Drive a re-armed PR-review step's RESOLUTION. The human resolved a parked review with `fix` or
+     * `post`; {@link PrReviewController.resolve} re-armed this step and woke the driver. Delegated to
+     * {@link PrReviewResolutionController} (the cohesive driver-side seam); see it for the `fix` /
+     * `post` mechanics.
      */
-    async dispatchPrReviewFixer(ctx) {
-        const { workspaceId, instance, step, block } = ctx;
-        const review = step.prReview;
-        const selected = (review.findings ?? []).filter((f) => review.selectedFindingIds?.includes(f.id));
-        let headRef = null;
-        let prNumber;
-        if (!step.jobId) {
-            prNumber = reviewPrNumber(block);
-            const runRepo = prNumber != null ? await this.resolveRunRepoContext?.(workspaceId, block.id) : null;
-            const repo = runRepo?.repo;
-            headRef =
-                prNumber != null && repo?.pullRequestHeadRef
-                    ? await this.runInitiatorScope(instance.initiatedBy, () => repo.pullRequestHeadRef(prNumber))
-                    : null;
-            if (prNumber == null || !headRef) {
-                return {
-                    kind: 'job_failed',
-                    failureKind: 'preflight',
-                    error: "Can't resolve the reviewed pull request's head branch to push fixes to. The " +
-                        "'fix' resolution needs a same-repo pull request on this service's linked repository " +
-                        '(a cross-repo or fork PR is not yet supported — post the findings as comments instead).',
-                };
-            }
-        }
-        const resolvedHeadRef = headRef;
-        const resolvedPrNumber = prNumber;
-        return this.handleAgentStep(ctx, FIXER_AGENT_KIND, (context) => {
-            if (resolvedHeadRef && resolvedPrNumber != null) {
-                context.block.pullRequest = {
-                    number: resolvedPrNumber,
-                    branch: resolvedHeadRef,
-                    url: review.prUrl ?? '',
-                };
-                // Build inside the PR head branch (probed, never created) so the work-branch machinery
-                // targets it rather than minting a stray `cat-factory/<blockId>` off base.
-                context.aprioriBranches = [{ name: resolvedHeadRef, mode: 'working' }];
-            }
-            context.priorOutputs = [
-                ...context.priorOutputs,
-                { agentKind: FIXER_AGENT_KIND, output: renderPrReviewFixerFeedback(selected) },
-            ];
-        });
-    }
-    /**
-     * Post a PR-review `post` resolution: publish the human-selected findings as a single advisory
-     * (`COMMENT`) inline review on the reviewed PR via the checkout-free `RepoFiles.createReview`,
-     * then finish the step. At-most-once: the `pendingPrReviewPost` marker is consumed (cleared +
-     * persisted) BEFORE the (side-effecting) post so a Workflows retry can't submit it twice. When
-     * no VCS review write is wired (tests / no GitHub) the findings are still recorded and the step
-     * finishes — the review pipeline never reaches this without GitHub in practice.
-     *
-     * If `createReview` itself throws (GitHub rejects the batched review — e.g. a finding anchored
-     * to a line outside the PR diff 422s the WHOLE review — or a transient network/5xx error), the
-     * marker is already consumed, so a driver retry would NOT re-post. Rather than silently
-     * completing the step as `done` with nothing actually posted (the human would believe the
-     * comments landed), fail the step LOUDLY so the failure surfaces on the board — mirroring the
-     * `fix` resolution's loud preflight failure. `post` is a fallback resolution, so a hard failure
-     * is visible and the human can re-run or choose `fix`/`finish` instead.
-     */
-    async postPrReview(ctx) {
-        const { workspaceId, instance, step, block, isFinalStep } = ctx;
-        const review = step.prReview;
-        const selected = (review.findings ?? []).filter((f) => review.selectedFindingIds?.includes(f.id));
-        let posted = false;
-        if (step.pendingPrReviewPost) {
-            step.pendingPrReviewPost = null;
-            await this.runStateMachine.casPersist(workspaceId, instance);
-            const prNumber = reviewPrNumber(block);
-            const runRepo = prNumber != null ? await this.resolveRunRepoContext?.(workspaceId, block.id) : null;
-            const repo = runRepo?.repo;
-            if (prNumber != null && repo?.createReview) {
-                try {
-                    await this.runInitiatorScope(instance.initiatedBy, () => repo.createReview(prNumber, buildPrReviewPost(selected, review.summary)));
-                }
-                catch (error) {
-                    return {
-                        kind: 'job_failed',
-                        failureKind: 'agent',
-                        error: `Failed to post the ${selected.length} selected finding` +
-                            `${selected.length === 1 ? '' : 's'} as a pull-request review: ${getErrorMessage(error)}. ` +
-                            'GitHub rejects a review whose inline comment anchors a line outside the PR diff — ' +
-                            "try the 'fix' resolution, or re-run to post again.",
-                    };
-                }
-                posted = true;
-            }
-        }
-        step.prReview = { ...review, status: 'done' };
-        const output = posted
-            ? `Posted ${selected.length} review comment${selected.length === 1 ? '' : 's'} to the pull request.`
-            : `Recorded ${selected.length} selected finding${selected.length === 1 ? '' : 's'}.`;
-        return this.recordStepResult(workspaceId, instance, step, isFinalStep, { output });
+    handlePrReviewResolution(ctx) {
+        return this.prReviewResolution.handle(ctx);
     }
     /** Read a run's active implementation-fork decision state, or null. */
     getForkDecision(workspaceId, executionId) {