@cat-factory/orchestration 0.36.5 → 0.37.1

package/dist/modules/execution/ExecutionService.js

@@ -11,6 +11,7 @@ import { CONFLICTS_AGENT_KIND, MERGER_AGENT_KIND, REQUIREMENTS_REVIEW_AGENT_KIND
 import { DEFAULT_FOLLOW_UP_MAX_LOOPS, FOLLOW_UP_PRODUCER_KIND, followUpsToSendBack, hasPendingFollowUps, renderFollowUpRework, shouldLoopCoder, } from './followUp.logic.js';
 import { AgentContextBuilder, } from './AgentContextBuilder.js';
 import { CompanionController } from './CompanionController.js';
+import { StepGraph } from './StepGraph.js';
 import { inferTechnicalLabel } from './technical.logic.js';
 import { MergeResolver } from './MergeResolver.js';
 import { ReviewGateController } from './ReviewGateController.js';
@@ -65,6 +66,16 @@ function parseRepoFromPullUrl(url) {
         return undefined;
     return { owner: match[1], repo: match[2] };
 }
+/**
+ * The inline review/brainstorm gate kinds, all driven through the {@link ReviewGateController}
+ * by the engine's `review-gate` StepHandler. Kept in sync with the handler's `switch`.
+ */
+const REVIEW_GATE_AGENT_KINDS = new Set([
+    REQUIREMENTS_REVIEW_AGENT_KIND,
+    CLARITY_REVIEW_AGENT_KIND,
+    REQUIREMENTS_BRAINSTORM_AGENT_KIND,
+    ARCHITECTURE_BRAINSTORM_AGENT_KIND,
+]);
 /**
  * The execution engine. It orchestrates a pipeline of agent-performed steps and
  * is fully deterministic: `advanceInstance` moves one run forward by exactly one
@@ -83,6 +94,8 @@ export class ExecutionService {
     accountRepository;
     idGenerator;
     clock;
+    /** The pure step/cursor mutators (start/finish/park/reset + the companion rework loop). */
+    stepGraph;
     agentExecutor;
     workRunner;
     events;
@@ -153,7 +166,12 @@ export class ExecutionService {
      * and {@link StepHandler}. Engine-internal (no public registration seam).
      */
     stepHandlerCache;
-    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, documentUrlResolver, taskRepository, requirementReviewRepository, requirementReviewService, kaizenScheduler, clarityReviewRepository, clarityReviewService, brainstormServices, brainstormSessionRepository, fragmentResolver, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, notificationService, binaryArtifactStore, workspaceSettingsService, llmObservability, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, resolveRunRepoContext, resolveTesterFallbackDefault, resolveRequireEnvironmentProvider, assertAgentBackendConfigured, runInitiatorScope, }) {
+    /**
+     * Lazily-built, order-sorted completion-path interceptor list (companion/tester verdict
+     * short-circuits). See {@link dispatchStepCompletionInterceptor}. Engine-internal.
+     */
+    stepCompletionInterceptorCache;
+    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, documentUrlResolver, taskRepository, requirementReviewRepository, requirementReviewService, kaizenScheduler, clarityReviewRepository, clarityReviewService, brainstormServices, brainstormSessionRepository, fragmentResolver, environmentProvisioning, environmentTeardown, branchUpdater, blueprintReconciler, notificationService, resolveBinaryArtifactStore, workspaceSettingsService, llmObservability, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, issueWriteback, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, resolveRunRepoContext, resolveTesterFallbackDefault, resolveRequireEnvironmentProvider, assertAgentBackendConfigured, runInitiatorScope, }) {
         this.runInitiatorScope = runInitiatorScope ?? ((_initiatedBy, fn) => fn());
         this.workspaceRepository = workspaceRepository;
         this.blockRepository = blockRepository;
@@ -162,6 +180,7 @@ export class ExecutionService {
         this.accountRepository = accountRepository;
         this.idGenerator = idGenerator;
         this.clock = clock;
+        this.stepGraph = new StepGraph(clock);
         this.agentExecutor = agentExecutor;
         this.workRunner = workRunner;
         this.events = executionEventPublisher;
@@ -200,9 +219,9 @@ export class ExecutionService {
             idGenerator,
             previewStepModel: (ctx) => this.previewStepModel(ctx),
             runAgent: (ctx, opts) => this.runAgent(ctx, opts),
-            finishStep: (s) => this.finishStep(s),
-            startStep: (s) => this.startStep(s),
-            pauseStepForInput: (s) => this.pauseStepForInput(s),
+            finishStep: (s) => this.stepGraph.finishStep(s),
+            startStep: (s) => this.stepGraph.startStep(s),
+            pauseStepForInput: (s) => this.stepGraph.pauseStepForInput(s),
             updateBlockProgress: (ws, i, st) => this.updateBlockProgress(ws, i, st),
             persistInstance: (ws, i) => this.executionRepository.upsert(ws, i),
             emitInstance: (ws, i) => this.emitInstance(ws, i),
@@ -210,7 +229,7 @@ export class ExecutionService {
             finalizeBlock: (ws, i, c) => this.finalizeBlock(ws, i, c),
             parkStepOnDecision: (ws, i, s, p) => this.parkStepOnDecision(ws, i, s, p),
             raiseDecisionRequired: (ws, i) => this.raiseDecisionRequired(ws, i),
-            loopCompanionProducer: (i, ci, rw) => this.loopCompanionProducer(i, ci, rw),
+            loopCompanionProducer: (i, ci, rw) => this.stepGraph.loopCompanionProducer(i, ci, rw),
             inferTechnicalLabel: (ws, block, producer, companionStep) => this.inferBlockTechnical(ws, block, producer, companionStep),
         });
         this.testerController = new TesterController({
@@ -255,8 +274,8 @@ export class ExecutionService {
             ...(branchUpdater ? { branchUpdater } : {}),
             resolveMergePreset: (ws, block) => this.resolveMergePreset(ws, block),
             parkStepOnDecision: (ws, i, s, p) => this.parkStepOnDecision(ws, i, s, p),
-            finishStep: (s) => this.finishStep(s),
-            startStep: (s) => this.startStep(s),
+            finishStep: (s) => this.stepGraph.finishStep(s),
+            startStep: (s) => this.stepGraph.startStep(s),
             updateBlockProgress: (ws, i, st) => this.updateBlockProgress(ws, i, st),
             finalizeBlock: (ws, i, c) => this.finalizeBlock(ws, i, c),
             stopRunContainer: (ws, i) => this.stopRunContainer(ws, i),
@@ -271,11 +290,11 @@ export class ExecutionService {
             agentExecutor,
             contextBuilder: this.contextBuilder,
             notificationService,
-            ...(binaryArtifactStore ? { binaryArtifactStore } : {}),
+            ...(resolveBinaryArtifactStore ? { resolveBinaryArtifactStore } : {}),
             resolveMergePreset: (ws, block) => this.resolveMergePreset(ws, block),
             parkStepOnDecision: (ws, i, s, p) => this.parkStepOnDecision(ws, i, s, p),
-            finishStep: (s) => this.finishStep(s),
-            startStep: (s) => this.startStep(s),
+            finishStep: (s) => this.stepGraph.finishStep(s),
+            startStep: (s) => this.stepGraph.startStep(s),
             updateBlockProgress: (ws, i, st) => this.updateBlockProgress(ws, i, st),
             finalizeBlock: (ws, i, c) => this.finalizeBlock(ws, i, c),
             stopRunContainer: (ws, i) => this.stopRunContainer(ws, i),
@@ -292,8 +311,8 @@ export class ExecutionService {
             advancePastResolvedGate: (ws, i, idx) => this.advancePastResolvedGate(ws, i, idx),
             dispatchIterationCap: (ws, blockId, choice, handlers) => this.dispatchIterationCap(ws, blockId, choice, handlers),
             raiseDecisionRequired: (ws, i) => this.raiseDecisionRequired(ws, i),
-            finishStep: (s) => this.finishStep(s),
-            startStep: (s) => this.startStep(s),
+            finishStep: (s) => this.stepGraph.finishStep(s),
+            startStep: (s) => this.stepGraph.startStep(s),
             updateBlockProgress: (ws, i, st) => this.updateBlockProgress(ws, i, st),
             finalizeBlock: (ws, i, c) => this.finalizeBlock(ws, i, c),
             stopRunContainer: (ws, i) => this.stopRunContainer(ws, i),
@@ -804,7 +823,7 @@ export class ExecutionService {
                 }
             }
         }
-        this.startStep(step);
+        this.stepGraph.startStep(step);
         const block = await this.blockRepository.get(workspaceId, instance.blockId);
         if (!block)
             return { kind: 'noop' };
@@ -819,7 +838,7 @@ export class ExecutionService {
         }
         // The fixed run-lifecycle preamble is done; hand the per-kind work to the
         // engine-internal StepHandler registry (the first handler whose `canHandle` claims
-        // this step). See {@link dispatchStepHandler} / {@link runStepBody}.
+        // this step). See {@link dispatchStepHandler} / {@link handleAgentStep}.
         return this.dispatchStepHandler({
             workspaceId,
             instance,
@@ -830,77 +849,16 @@ export class ExecutionService {
         });
     }
     /**
-     * The per-step-kind body run by the StepHandler registry once {@link stepInstance}'s
-     * preamble has completed. Phase 0 of the ExecutionService split: a single fallthrough
-     * handler delegates the ENTIRE body here unchanged (so dispatch is wired with zero
-     * behaviour change); later phases lift each branch below into its own handler and shrink
-     * this method until only the generic container/inline-agent tail remains.
+     * The generic container/inline-agent step — the lowest-priority StepHandler, claiming
+     * every step no more-specific handler did (coder, architect, spec-writer, merger,
+     * task-estimator, the container-backed companions, …). Builds the agent context, runs the
+     * kind's pre-ops, then either dispatches an async container job and parks (the durable
+     * driver polls between sleeps) or runs the inline LLM call and records the result. This is
+     * what the dispatch chain falls through to; all the deterministic / gate / inline-review
+     * kinds are claimed earlier by their own handlers (see {@link buildStepHandlerRegistry}).
      */
-    async runStepBody(ctx) {
+    async handleAgentStep(ctx) {
         const { workspaceId, instance, step, block, isFinalStep, options } = ctx;
-        // (The `deployer` and `tracker` steps are handled by their own StepHandlers — see
-        // {@link buildStepHandlerRegistry} — so they no longer branch here.)
-        // A `requirements-review` step runs the inline reviewer and parks for the dedicated
-        // review window, driving the iterative answer → incorporate → re-review loop. NOT a
-        // container/prose agent. Pass-through when the reviewer isn't wired. The clarity gate
-        // shares the SAME flow (only the subject + persisted doc differ); both run through the
-        // {@link ReviewGateController}, parameterised by their {@link ReviewKind}.
-        if (step.agentKind === REQUIREMENTS_REVIEW_AGENT_KIND) {
-            return this.reviewGate.evaluate(this.requirementsKind, workspaceId, instance, step, block, isFinalStep);
-        }
-        // A `clarity-review` step triages the block's bug report (optionally enriched by an
-        // upstream `bug-investigator` step) and parks for the dedicated review window, driving
-        // the same iterative loop as the requirements gate. NOT a container/prose agent.
-        // Pass-through when the reviewer isn't wired.
-        if (step.agentKind === CLARITY_REVIEW_AGENT_KIND) {
-            return this.reviewGate.evaluate(this.clarityKind, workspaceId, instance, step, block, isFinalStep);
-        }
-        // The two brainstorm (structured-dialogue) gates run the inline option-generator and park
-        // for the dedicated brainstorm window, driving the same iterative loop as the requirements
-        // gate. NOT container/prose agents. Pass-through when the brainstorm module isn't wired.
-        if (step.agentKind === REQUIREMENTS_BRAINSTORM_AGENT_KIND) {
-            return this.reviewGate.evaluate(this.requirementsBrainstormKind, workspaceId, instance, step, block, isFinalStep);
-        }
-        if (step.agentKind === ARCHITECTURE_BRAINSTORM_AGENT_KIND) {
-            return this.reviewGate.evaluate(this.architectureBrainstormKind, workspaceId, instance, step, block, isFinalStep);
-        }
-        // A `human-test` gate spins up an ephemeral environment and PARKS for a human to
-        // validate the change in a live URL before the run continues — NOT a container/prose
-        // agent and NOT a programmatic polling gate (the human is the verdict). It also drives
-        // the same helpers the other gates use on demand: the Tester's `fixer` (from findings)
-        // and the `conflict-resolver` (after a conflicting pull-main). Degrades to a manual
-        // (no-env) mode when no ephemeral-environment provider is wired. See {@link HumanTestController}.
-        if (step.agentKind === HUMAN_TEST_AGENT_KIND) {
-            return this.humanTestController.evaluate(workspaceId, instance, step, block, isFinalStep);
-        }
-        // A `visual-confirmation` gate gathers the UI tester's screenshots + the uploaded
-        // reference designs and PARKS for a human to review actual-vs-reference, then on demand
-        // dispatches the Tester's `fixer`. Passes through (auto-advances) when no binary-artifact
-        // store is wired. See {@link VisualConfirmationController}.
-        if (step.agentKind === VISUAL_CONFIRM_AGENT_KIND) {
-            return this.visualConfirmationController.evaluate(workspaceId, instance, step, block, isFinalStep);
-        }
-        // A polling gate step (`ci` / `conflicts`) runs a programmatic precheck and only
-        // escalates to a helper container agent (`ci-fixer` / `conflict-resolver`) on a
-        // negative verdict — no LLM of its own. Pass-through when the gate's provider is
-        // not wired. One generic machine drives every gate; see {@link evaluateGate}.
-        const gate = this.gateFor(step.agentKind);
-        if (gate) {
-            return this.evaluateGate(workspaceId, instance, step, block, isFinalStep, gate);
-        }
-        // A companion step grades the nearest preceding producer of one of its target
-        // kinds, looping it back for automatic rework below the threshold (and failing
-        // the run once the budget is spent) before any human gate. See evaluateCompanion.
-        //
-        // INLINE companions (architect-companion / spec-companion) run their LLM grading right
-        // here. CONTAINER-backed companions (reviewer / doc-reviewer) instead fall through to the
-        // generic async container dispatch below — they clone the producer's PR branch and review
-        // the REAL repository — and their verdict is resolved in `recordStepResult` via
-        // `companionController.resolveContainerVerdict` (which runs the SAME threshold / rework
-        // loop). A summary-only review is useless; the container reviewer reads the actual diff.
-        if (isCompanionKind(step.agentKind) && !isContainerBackedCompanion(step.agentKind)) {
-            return this.companionController.evaluate(workspaceId, instance, step, block, isFinalStep, options);
-        }
         // Async (container) steps don't block: dispatch the job and park. The durable
         // driver polls `pollAgentJob` between sleeps so the run can span far longer
         // than a single durable step's timeout, while each step stays short. A set
@@ -1434,29 +1392,6 @@ export class ExecutionService {
             return false;
         }
     }
-    startStep(step) {
-        step.state = 'working';
-        if (step.startedAt == null)
-            step.startedAt = this.clock.now();
-        // (Re)entering `working` means the step is no longer parked on a human: resume
-        // its duration clock (see {@link pauseStepForInput}).
-        step.pausedAt = null;
-    }
-    /**
-     * Transition a step into `done`, stamping its finish time once. Set-once so the
-     * approval-gate flow (which re-asserts `done` after a human approves, long after
-     * the agent actually finished) keeps the agent's true completion time, and so a
-     * replay doesn't move it. With {@link startStep}'s `startedAt` this yields the
-     * step's execution duration. A step finished directly out of a parked approval
-     * stopped *working* when it parked, so its duration is billed to the pause instant
-     * ({@link pauseStepForInput}), not the (later) moment the human decided.
-     */
-    finishStep(step) {
-        step.state = 'done';
-        if (step.finishedAt == null)
-            step.finishedAt = step.pausedAt ?? this.clock.now();
-        step.pausedAt = null;
-    }
     /**
      * Finish a gated step that was skipped (its estimate gate was not satisfied) and either
      * complete the run or advance to the next step — the deterministic finish/advance tail
@@ -1469,7 +1404,7 @@ export class ExecutionService {
         step.output = '';
         step.progress = 1;
         step.subtasks = undefined;
-        this.finishStep(step);
+        this.stepGraph.finishStep(step);
         if (isFinalStep) {
             instance.status = 'done';
             await this.finalizeBlock(workspaceId, instance, undefined);
@@ -1481,24 +1416,12 @@ export class ExecutionService {
         instance.currentStep += 1;
         const next = instance.steps[instance.currentStep];
         if (next)
-            this.startStep(next);
+            this.stepGraph.startStep(next);
         await this.updateBlockProgress(workspaceId, instance, 'in_progress');
         await this.executionRepository.upsert(workspaceId, instance);
         await this.emitInstance(workspaceId, instance);
         return { kind: 'continue' };
     }
-    /**
-     * Park a step on a human decision and freeze its duration clock. Records when the
-     * step stopped working (`pausedAt`) so elapsed time no longer accrues while it waits
-     * for input — the symmetric counterpart of the terminal freeze on `finishedAt`.
-     * Set-once (a Workflows replay re-parking keeps the original instant); cleared when
-     * the step resumes ({@link startStep}) or finishes ({@link finishStep}).
-     */
-    pauseStepForInput(step) {
-        step.state = 'waiting_decision';
-        if (step.pausedAt == null)
-            step.pausedAt = this.clock.now();
-    }
     /**
      * Infer + persist the block's `technical` label from the settled spec phase (item 5):
      * combine the spec-writer's `noBusinessSpecs` determination (recorded on the producer
@@ -1542,33 +1465,28 @@ export class ExecutionService {
                 options: [...result.decision.options],
                 chosen: null,
             };
-            this.pauseStepForInput(step);
+            this.stepGraph.pauseStepForInput(step);
             instance.status = 'blocked';
             await this.updateBlockProgress(workspaceId, instance, 'blocked');
             await this.executionRepository.upsert(workspaceId, instance);
             await this.emitInstance(workspaceId, instance);
             return { kind: 'awaiting_decision', decisionId: step.decision.id };
         }
-        // A container-backed companion (reviewer / doc-reviewer) just finished reviewing the
-        // real repository on the producer's PR branch and returned its verdict as `result.custom`.
-        // Hand it to the companion loop, which parses the verdict and applies the SAME threshold /
-        // rework / human-gate handling an inline companion gets. Routed here (not the normal step
-        // completion) so the verdict drives the loop instead of being recorded as plain output.
-        if (isCompanionKind(step.agentKind) && isContainerBackedCompanion(step.agentKind)) {
-            const companionBlock = await this.blockRepository.get(workspaceId, instance.blockId);
-            if (companionBlock) {
-                return this.companionController.resolveContainerVerdict(workspaceId, instance, step, companionBlock, isFinalStep, result);
-            }
-        }
-        // A `tester` step returned a structured report. On a withheld greenlight we do
-        // NOT finish the step: we loop the `fixer` (within the attempt budget) and
-        // re-test, mirroring the CI gate. A greenlight (or no provider) falls through to
-        // the normal finish/advance below. Records the report on the step either way.
-        if (isTesterKind(step.agentKind) && result.testReport !== undefined) {
-            const looped = await this.testerController.resolveTesterResult(workspaceId, instance, step, result);
-            if (looped)
-                return looped;
-        }
+        // 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
+        // threshold/rework/human-gate loop, and a Tester re-runs its `fixer` on a withheld
+        // greenlight. A non-null outcome replaces the normal completion; null (a Tester
+        // greenlight, or a companion whose block can't be loaded) falls through. See
+        // {@link buildStepCompletionInterceptors}.
+        const intercepted = await this.dispatchStepCompletionInterceptor({
+            workspaceId,
+            instance,
+            step,
+            isFinalStep,
+            result,
+        });
+        if (intercepted)
+            return intercepted;
         // The step completed.
         step.output = result.output ?? '';
         // Surface a registered custom kind's structured JSON on the step so the SPA's
@@ -1579,7 +1497,7 @@ export class ExecutionService {
         if (result.model)
             step.model = result.model;
         step.progress = 1;
-        this.finishStep(step);
+        this.stepGraph.finishStep(step);
         // Live subtask counts only describe an in-flight run; drop them now the step
         // is done so the board doesn't show a stale "3/8" against a finished step.
         step.subtasks = undefined;
@@ -1612,38 +1530,25 @@ export class ExecutionService {
                     .catch(() => { });
             }
         }
-        // A Blueprinter step produced a fresh service decomposition. Validate it with
-        // the authoritative schema (a bad payload must never touch the board), then
-        // reconcile it in place onto the run's service frame.
-        if (result.blueprintService !== undefined) {
-            await this.ingestBlueprint(workspaceId, instance.blockId, result.blueprintService);
-        }
-        // A spec-writer step produced the service's unified specification (`spec.json`)
-        // and committed it to the implementation branch. Strict-validate it (a bad payload
-        // must never be trusted), then nudge clients to refresh.
-        if (result.spec !== undefined) {
-            await this.ingestSpec(workspaceId, result.spec);
-        }
-        // Record the spec-writer's BUSINESS-vs-TECHNICAL determination on the step. "No
-        // business specs" (a purely technical task) is a valid outcome; the spec-companion's
-        // convergence — the one point both signals coexist — combines this with the
-        // companion's `technicalCorroborated` verdict to infer the block's `technical` label
-        // (see CompanionController). Recorded even when false so a re-run reflects the latest.
-        if (step.agentKind === SPEC_WRITER_AGENT_KIND) {
-            step.noBusinessSpecs = result.noBusinessSpecs === true;
-        }
-        // A `task-estimator` step emits a JSON triage (complexity/risk/impact). Parse it
-        // tolerantly, persist it on the block (used to gate consensus steps + surfaced in
-        // the UI), and replace the raw JSON output with a readable summary. An unparseable
-        // estimate leaves the block untouched and keeps the raw output (no run failure).
-        // The estimate works the same whether the single-actor estimator or the consensus
-        // ranked-scoring variant produced the JSON — both land here.
-        if (step.agentKind === TASK_ESTIMATOR_AGENT_KIND) {
-            const estimate = coerceTaskEstimate(step.output, result.model ?? step.model ?? null, this.clock.now());
-            if (estimate) {
-                await this.blockRepository.update(workspaceId, instance.blockId, { estimate });
-                step.output = summarizeEstimate(estimate);
-            }
+        // 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
+        // POSITION is load-bearing — it runs after the output is recorded but BEFORE the
+        // 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;
         }
         // 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.
@@ -1679,7 +1584,7 @@ export class ExecutionService {
                 status: 'pending',
                 proposal: step.output,
             };
-            this.pauseStepForInput(step);
+            this.stepGraph.pauseStepForInput(step);
             instance.status = 'blocked';
             await this.updateBlockProgress(workspaceId, instance, 'blocked');
             await this.executionRepository.upsert(workspaceId, instance);
@@ -1702,7 +1607,9 @@ export class ExecutionService {
         // tells `finalizeBlock` to leave it alone.
         const resolver = this.stepResolverFor(step.agentKind);
         let resolverOwnsTerminalStatus = false;
-        if (resolver && (resolver.applies?.(result) ?? true)) {
+        if (resolver &&
+            (resolver.phase ?? 'terminal') === 'terminal' &&
+            (resolver.applies?.(result) ?? true)) {
             const resolution = await resolver.resolve({
                 workspaceId,
                 instance,
@@ -1740,7 +1647,7 @@ export class ExecutionService {
         instance.currentStep += 1;
         const next = instance.steps[instance.currentStep];
         if (next)
-            this.startStep(next);
+            this.stepGraph.startStep(next);
         // A resolver that already set the block's TERMINAL status (the merger flips it to
         // `done`/`pr_ready` mid-pipeline) must not be clobbered back to `in_progress` as we
         // advance to a trailing step — refresh progress only, preserving that status. (The
@@ -1755,74 +1662,6 @@ export class ExecutionService {
         await this.emitInstance(workspaceId, instance);
         return { kind: 'continue' };
     }
-    /**
-     * Reset a step so the durable driver re-runs it from scratch: clear its live
-     * container job handle (so it dispatches FRESH work rather than re-attaching to a
-     * finished or evicted job), its timings, approval gate, live subtasks and last
-     * output, and drop it back to `pending`. Preserves the step's identity
-     * (`agentKind` / `requiresApproval`) and any companion budget/verdict history.
-     */
-    resetStepForRerun(step) {
-        step.state = 'pending';
-        step.startedAt = null;
-        step.finishedAt = null;
-        step.pausedAt = null;
-        step.jobId = undefined;
-        step.approval = null;
-        step.subtasks = undefined;
-        step.progress = 0;
-        step.output = undefined;
-        // Drop the prior run's structured output too, so a re-run that produces no `custom`
-        // doesn't leave stale JSON for the `generic-structured` result view to render.
-        step.custom = undefined;
-        step.rework = undefined;
-    }
-    /**
-     * Loop a producer step back for rework and re-run every step from it up to and
-     * including the companion at `companionIndex`: each one is reset (crucially clearing
-     * stale container job handles so an intermediate container step re-dispatches fresh
-     * work instead of re-attaching to its evicted job), the producer is handed the
-     * `rework` feedback + started, and the instance cursor is moved back to the producer.
-     * Shared by the automatic companion loop and the human "request changes" path.
-     */
-    rerunProducerThrough(instance, producerIndex, companionIndex, rework) {
-        for (let i = producerIndex; i <= companionIndex; i++) {
-            this.resetStepForRerun(instance.steps[i]);
-        }
-        const producer = instance.steps[producerIndex];
-        producer.rework = rework;
-        this.startStep(producer);
-        instance.currentStep = producerIndex;
-    }
-    /**
-     * The index of the nearest preceding step a companion grades (one of its target
-     * producer kinds), or -1 when none precedes it. The single producer-search used by the
-     * automatic companion loop, the human "request changes" redirect, and the iteration-cap
-     * extra-round resolution.
-     */
-    companionProducerIndex(instance, companionIndex) {
-        const targets = companionTargets(instance.steps[companionIndex].agentKind);
-        for (let i = companionIndex - 1; i >= 0; i--) {
-            if (targets.includes(instance.steps[i].agentKind))
-                return i;
-        }
-        return -1;
-    }
-    /**
-     * Loop a companion's producer back for one more automatic rework cycle: charge one
-     * attempt against the budget, then re-run the producer (and any intermediate steps) up
-     * to and including the companion so it re-grades. Shared by the automatic
-     * below-threshold loop ({@link evaluateCompanion}) and the human-granted extra round
-     * ({@link resolveCompanionExceeded}), so both consume the budget identically.
-     */
-    loopCompanionProducer(instance, companionIndex, rework) {
-        const companionStep = instance.steps[companionIndex];
-        const producerIndex = this.companionProducerIndex(instance, companionIndex);
-        companionStep.companion.attempts += 1;
-        this.rerunProducerThrough(instance, producerIndex, companionIndex, rework);
-        if (instance.status === 'blocked')
-            instance.status = 'running';
-    }
     /**
      * Deterministically provision an ephemeral environment for a deployer step.
      * Produces a human-readable summary as the step output and reports no token
@@ -2118,17 +1957,144 @@ export class ExecutionService {
                     return this.recordStepResult(workspaceId, instance, step, isFinalStep, result);
                 },
             },
-            // The generic container/inline-agent fallthrough — claims every step no more-specific
-            // handler did (today's `runStepBody` tail). Highest order so it always runs last.
+            // The `requirements-review` / `clarity-review` / `requirements-brainstorm` /
+            // `architecture-brainstorm` steps are inline reviewers that park for their dedicated
+            // window and drive the iterative answer → incorporate → re-review loop — NOT
+            // container/prose agents. All four run through the {@link ReviewGateController},
+            // parameterised by their {@link ReviewKind} (the per-case `switch` binds each kind's
+            // review type so `evaluate`'s generic infers). Pass-through when the service isn't wired.
+            {
+                kind: 'review-gate',
+                order: 120,
+                canHandle: ({ step }) => REVIEW_GATE_AGENT_KINDS.has(step.agentKind),
+                handle: ({ workspaceId, instance, step, block, isFinalStep }) => {
+                    switch (step.agentKind) {
+                        case REQUIREMENTS_REVIEW_AGENT_KIND:
+                            return this.reviewGate.evaluate(this.requirementsKind, workspaceId, instance, step, block, isFinalStep);
+                        case CLARITY_REVIEW_AGENT_KIND:
+                            return this.reviewGate.evaluate(this.clarityKind, workspaceId, instance, step, block, isFinalStep);
+                        case REQUIREMENTS_BRAINSTORM_AGENT_KIND:
+                            return this.reviewGate.evaluate(this.requirementsBrainstormKind, workspaceId, instance, step, block, isFinalStep);
+                        case ARCHITECTURE_BRAINSTORM_AGENT_KIND:
+                            return this.reviewGate.evaluate(this.architectureBrainstormKind, workspaceId, instance, step, block, isFinalStep);
+                        // `canHandle` admits only the kinds in REVIEW_GATE_AGENT_KINDS, so every member
+                        // must have an explicit case above. Throw loudly if the two ever drift (a new
+                        // review kind added to the Set without a case here) rather than silently routing
+                        // it to the wrong reviewer.
+                        default:
+                            throw new Error(`Unhandled review-gate agentKind "${step.agentKind}"`);
+                    }
+                },
+            },
+            // A `human-test` gate spins up an ephemeral environment and PARKS for a human to
+            // validate the change in a live URL — NOT a container/prose agent and NOT a
+            // programmatic polling gate (the human is the verdict). Degrades to a manual (no-env)
+            // mode when no ephemeral-environment provider is wired. See {@link HumanTestController}.
             {
-                kind: '*',
+                kind: HUMAN_TEST_AGENT_KIND,
+                order: 130,
+                canHandle: ({ step }) => step.agentKind === HUMAN_TEST_AGENT_KIND,
+                handle: ({ workspaceId, instance, step, block, isFinalStep }) => this.humanTestController.evaluate(workspaceId, instance, step, block, isFinalStep),
+            },
+            // A `visual-confirmation` gate gathers the UI tester's screenshots + uploaded reference
+            // designs and PARKS for a human to review actual-vs-reference, then on demand dispatches
+            // the Tester's `fixer`. Passes through when no binary-artifact store is wired.
+            // See {@link VisualConfirmationController}.
+            {
+                kind: VISUAL_CONFIRM_AGENT_KIND,
+                order: 140,
+                canHandle: ({ step }) => step.agentKind === VISUAL_CONFIRM_AGENT_KIND,
+                handle: ({ workspaceId, instance, step, block, isFinalStep }) => this.visualConfirmationController.evaluate(workspaceId, instance, step, block, isFinalStep),
+            },
+            // A polling gate step (`ci` / `conflicts` / `post-release-health` / `human-review`) runs
+            // a programmatic precheck and only escalates to a helper container agent on a negative
+            // verdict — no LLM of its own. Pass-through when the gate's provider is not wired. One
+            // generic machine drives every gate; see {@link evaluateGate}. `canHandle` is the gate
+            // registry lookup, so this claims exactly the registered gate kinds.
+            {
+                kind: 'polling-gate',
+                order: 150,
+                canHandle: ({ step }) => this.gateFor(step.agentKind) !== undefined,
+                handle: ({ workspaceId, instance, step, block, isFinalStep }) => this.evaluateGate(workspaceId, instance, step, block, isFinalStep, this.gateFor(step.agentKind)),
+            },
+            // An INLINE companion (architect-companion / spec-companion) grades the nearest
+            // preceding producer right here and loops it back for automatic rework below the
+            // threshold before any human gate. CONTAINER-backed companions (reviewer / doc-reviewer)
+            // do NOT match — they fall through to the generic async container dispatch and have their
+            // verdict resolved by the completion interceptor instead. See {@link CompanionController}.
+            {
+                kind: 'inline-companion',
+                order: 160,
+                canHandle: ({ step }) => isCompanionKind(step.agentKind) && !isContainerBackedCompanion(step.agentKind),
+                handle: ({ workspaceId, instance, step, block, isFinalStep, options }) => this.companionController.evaluate(workspaceId, instance, step, block, isFinalStep, options),
+            },
+            // The generic container/inline-agent step — claims every step no more-specific handler
+            // did. Highest order so it always runs last. See {@link handleAgentStep}.
+            {
+                kind: 'agent',
                 order: FALLTHROUGH_STEP_HANDLER_ORDER,
                 canHandle: () => true,
-                handle: (ctx) => this.runStepBody(ctx),
+                handle: (ctx) => this.handleAgentStep(ctx),
             },
         ];
         return handlers.sort((a, b) => a.order - b.order);
     }
+    /**
+     * Run the first completion-path interceptor that claims this finished step, returning its
+     * short-circuit {@link AdvanceResult} (the companion verdict loop / tester re-test) or
+     * `null` to let `recordStepResult`'s normal finish/advance spine run. Engine-internal,
+     * mirroring {@link dispatchStepHandler}.
+     */
+    async dispatchStepCompletionInterceptor(ctx) {
+        if (!this.stepCompletionInterceptorCache) {
+            this.stepCompletionInterceptorCache = this.buildStepCompletionInterceptors();
+        }
+        for (const interceptor of this.stepCompletionInterceptorCache) {
+            if (interceptor.canIntercept(ctx)) {
+                const outcome = await interceptor.intercept(ctx);
+                if (outcome)
+                    return outcome;
+            }
+        }
+        return null;
+    }
+    /**
+     * Build the order-sorted completion-path interceptors (companion / tester verdict
+     * short-circuits), mirroring {@link buildStepHandlerRegistry} — built-ins constructed
+     * inline closing over `this`, no public registration seam.
+     */
+    buildStepCompletionInterceptors() {
+        const interceptors = [
+            // A container-backed companion (reviewer / doc-reviewer) just finished reviewing the
+            // real repository on the producer's PR branch and returned its verdict as
+            // `result.custom`. Hand it to the companion loop, which parses the verdict and applies
+            // the SAME threshold / rework / human-gate handling an inline companion gets. Routed
+            // here (not the normal step completion) so the verdict drives the loop instead of being
+            // recorded as plain output. Falls through (returns null) when the block can't be loaded.
+            {
+                kind: 'companion-verdict',
+                order: 100,
+                canIntercept: ({ step }) => isCompanionKind(step.agentKind) && isContainerBackedCompanion(step.agentKind),
+                intercept: async ({ workspaceId, instance, step, isFinalStep, result }) => {
+                    const companionBlock = await this.blockRepository.get(workspaceId, instance.blockId);
+                    if (!companionBlock)
+                        return null;
+                    return this.companionController.resolveContainerVerdict(workspaceId, instance, step, companionBlock, isFinalStep, result);
+                },
+            },
+            // A `tester` step returned a structured report. On a withheld greenlight we do NOT
+            // finish the step: loop the `fixer` (within the attempt budget) and re-test, mirroring
+            // the CI gate. A greenlight (or no provider) returns null and falls through to the
+            // normal finish/advance below. Records the report on the step either way.
+            {
+                kind: 'tester-verdict',
+                order: 110,
+                canIntercept: ({ step, result }) => isTesterKind(step.agentKind) && result.testReport !== undefined,
+                intercept: ({ workspaceId, instance, step, result }) => this.testerController.resolveTesterResult(workspaceId, instance, step, result),
+            },
+        ];
+        return interceptors.sort((a, b) => a.order - b.order);
+    }
     stepResolverFor(agentKind) {
         if (!this.stepResolverCache)
             this.stepResolverCache = this.buildStepResolverRegistry();
@@ -2151,6 +2117,55 @@ export class ExecutionService {
                     return { ownsTerminalStatus: true };
                 },
             },
+            // POST-COMPLETION resolvers — run at the early slot (after output is recorded, before
+            // the follow-up/approval gates), reshaping the agent's structured result into domain
+            // state. Lifted verbatim from the old inline `recordStepResult` branches.
+            //
+            // A Blueprinter step produced a fresh service decomposition. Validate it with the
+            // authoritative schema (a bad payload must never touch the board), then reconcile it
+            // in place onto the run's service frame.
+            {
+                kind: BLUEPRINTS_AGENT_KIND,
+                phase: 'post-completion',
+                resolve: async ({ workspaceId, instance, result }) => {
+                    if (result.blueprintService !== undefined) {
+                        await this.ingestBlueprint(workspaceId, instance.blockId, result.blueprintService);
+                    }
+                },
+            },
+            // A spec-writer step produced the service's unified specification (`spec.json`) and
+            // committed it to the implementation branch — strict-validate it then nudge clients —
+            // and reports its BUSINESS-vs-TECHNICAL determination. "No business specs" (a purely
+            // technical task) is a valid outcome the spec-companion's convergence later combines
+            // with its `technicalCorroborated` verdict; recorded even when false so a re-run
+            // reflects the latest.
+            {
+                kind: SPEC_WRITER_AGENT_KIND,
+                phase: 'post-completion',
+                resolve: async ({ workspaceId, step, result }) => {
+                    if (result.spec !== undefined)
+                        await this.ingestSpec(workspaceId, result.spec);
+                    step.noBusinessSpecs = result.noBusinessSpecs === true;
+                },
+            },
+            // A `task-estimator` step emits a JSON triage (complexity/risk/impact). Parse it
+            // tolerantly, persist it on the block (used to gate consensus steps + surfaced in the
+            // UI), and replace the raw JSON output with a readable summary. An unparseable estimate
+            // leaves the block untouched and keeps the raw output (no run failure). Works the same
+            // whether the single-actor estimator or the consensus ranked-scoring variant produced
+            // the JSON. Running at the post-completion slot keeps the summary in `step.output`
+            // before the approval gate reads it as the proposal.
+            {
+                kind: TASK_ESTIMATOR_AGENT_KIND,
+                phase: 'post-completion',
+                resolve: async ({ workspaceId, instance, step, result }) => {
+                    const estimate = coerceTaskEstimate(step.output ?? '', result.model ?? step.model ?? null, this.clock.now());
+                    if (estimate) {
+                        await this.blockRepository.update(workspaceId, instance.blockId, { estimate });
+                        return { output: summarizeEstimate(estimate) };
+                    }
+                },
+            },
         ];
         const map = new Map(resolvers.map((r) => [r.kind, r]));
         // Merge deployment-registered resolvers, mirroring the gate registry below. A
@@ -2462,9 +2477,9 @@ export class ExecutionService {
         state.loops = (state.loops ?? 0) + 1;
         // Reset the step for a fresh dispatch; `step.followUps` is intentionally preserved
         // (resetStepForRerun doesn't touch it) so the surfaced items survive the loop.
-        this.resetStepForRerun(step);
+        this.stepGraph.resetStepForRerun(step);
         step.rework = { previousProposal: '', feedback };
-        this.startStep(step);
+        this.stepGraph.startStep(step);
         if (instance.status === 'blocked')
             instance.status = 'running';
     }
@@ -2760,7 +2775,7 @@ export class ExecutionService {
      */
     async parkStepOnDecision(workspaceId, instance, step, proposal = '') {
         step.approval = { id: this.idGenerator.next('appr'), status: 'pending', proposal };
-        this.pauseStepForInput(step);
+        this.stepGraph.pauseStepForInput(step);
         instance.status = 'blocked';
         await this.updateBlockProgress(workspaceId, instance, 'blocked');
         await this.executionRepository.upsert(workspaceId, instance);
@@ -3041,8 +3056,8 @@ export class ExecutionService {
             extraRound: async () => {
                 step.companion.maxAttempts += 1;
                 step.companion.exceeded = undefined;
-                const producer = instance.steps[this.companionProducerIndex(instance, stepIndex)];
-                this.loopCompanionProducer(instance, stepIndex, {
+                const producer = instance.steps[this.stepGraph.companionProducerIndex(instance, stepIndex)];
+                this.stepGraph.loopCompanionProducer(instance, stepIndex, {
                     previousProposal: producer?.output ?? '',
                     feedback: step.companion.verdicts.at(-1)?.feedback ?? '',
                 });
@@ -3060,7 +3075,7 @@ export class ExecutionService {
                 // so infer the block's `technical` label here too — best-effort, human-authority
                 // preserved — before advancing.
                 if (step.agentKind === 'spec-companion') {
-                    const producer = instance.steps[this.companionProducerIndex(instance, stepIndex)];
+                    const producer = instance.steps[this.stepGraph.companionProducerIndex(instance, stepIndex)];
                     const block = await this.blockRepository.get(workspaceId, instance.blockId);
                     if (producer && block)
                         await this.inferBlockTechnical(workspaceId, block, producer, step);
@@ -3081,7 +3096,7 @@ export class ExecutionService {
     async advancePastResolvedGate(workspaceId, instance, stepIndex) {
         const step = instance.steps[stepIndex];
         const decisionId = step.approval.id;
-        this.finishStep(step);
+        this.stepGraph.finishStep(step);
         step.progress = 1;
         const isFinalStep = stepIndex === instance.steps.length - 1;
         if (isFinalStep) {
@@ -3093,7 +3108,7 @@ export class ExecutionService {
             instance.currentStep = stepIndex + 1;
             const next = instance.steps[instance.currentStep];
             if (next)
-                this.startStep(next);
+                this.stepGraph.startStep(next);
             if (instance.status === 'blocked')
                 instance.status = 'running';
             await this.updateBlockProgress(workspaceId, instance, 'in_progress');
@@ -3541,7 +3556,7 @@ export class ExecutionService {
         if (!step || !step.decision)
             throw new NotFoundError('Decision', decisionId);
         step.decision.chosen = choice;
-        this.startStep(step);
+        this.stepGraph.startStep(step);
         if (instance.status === 'blocked')
             instance.status = 'running';
         await this.updateBlockProgress(workspaceId, instance, 'in_progress');
@@ -3630,7 +3645,7 @@ export class ExecutionService {
                 // including the companion, then the companion re-grades. Does NOT touch the
                 // companion's automatic-rework budget — a human-driven iteration is unbounded.
                 const previousProposal = producer.output ?? step.approval.proposal;
-                this.rerunProducerThrough(instance, producerIndex, stepIndex, {
+                this.stepGraph.rerunProducerThrough(instance, producerIndex, stepIndex, {
                     previousProposal,
                     feedback: review.feedback ?? '',
                     ...(review.comments?.length ? { comments: review.comments } : {}),
@@ -3650,7 +3665,7 @@ export class ExecutionService {
         // start/finish times this attempt rather than spanning the human gate wait.
         step.startedAt = null;
         step.finishedAt = null;
-        this.startStep(step);
+        this.stepGraph.startStep(step);
         if (instance.status === 'blocked')
             instance.status = 'running';
         await this.executionRepository.upsert(workspaceId, instance);