@cat-factory/orchestration 0.129.6 → 0.129.8

package/dist/modules/execution/RunDispatcher.js

@@ -527,65 +527,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, returning whether anything changed. 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 applyRunningFold = async (target) => {
-                const s = target.steps[target.currentStep];
-                // The step advanced (or the job was superseded) under a concurrent write — nothing to fold.
-                if (!s || s.jobId !== step.jobId)
-                    return false;
-                let changed = false;
-                if (this.applyContainerRunning(s, update))
-                    changed = true;
-                if (this.applySubtaskProgress(s, update.subtasks))
-                    changed = true;
-                // The transport reports WHICH backend served the job on the first poll (native host
-                // process vs. sandboxed container) — record it in the run diagnostics.
-                if (this.recordBackendDiagnostics(target, update.backend))
-                    changed = true;
-                // Append any forward-looking items the Coder streamed since the last poll so the
-                // Follow-up companion lights up + accrues items LIVE while the container still runs.
-                if (this.followUpGate.appendStreamedFollowUps(s, update.followUps))
-                    changed = true;
-                // Refresh the env projection so its status transitions (provisioning→ready→
-                // expired/torn_down) and any error stay live in the run details during the run.
-                if (await this.deployer.attachEnvironmentProjection(workspaceId, target.blockId, s))
-                    changed = true;
-                return changed;
-            };
-            // 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 applyRunningFold(instance)) {
-                try {
-                    const persisted = await this.runStateMachine.mutateInstance(workspaceId, executionId, async (fresh) => {
-                        await applyRunningFold(fresh);
-                    });
-                    // 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
@@ -594,34 +536,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
@@ -630,50 +547,7 @@ export class RunDispatcher {
         // negative, so the next check re-dispatches (until the attempt budget is spent).
         const reprobeGate = this.gateFor(step.agentKind);
         if (reprobeGate) {
-            // A gate may need deterministic GitHub-side bookkeeping to land BEFORE the re-probe
-            // reads it (the human-review gate replies to + RESOLVES the threads it handed the
-            // fixer, so the next probe counts them addressed). Run that side-effect hook first;
-            // it does NOT replace the re-probe (unlike resolveHelperCompletion).
-            if (reprobeGate.onHelperComplete && step.gate) {
-                const block = await this.blockRepository.get(workspaceId, instance.blockId);
-                if (block) {
-                    const jobResult = update.state === 'done'
-                        ? { state: 'done', result: update.result }
-                        : { state: 'failed', error: update.error ?? null };
-                    await this.runInitiatorScope(instance.initiatedBy, () => reprobeGate.onHelperComplete({
-                        workspaceId,
-                        instance,
-                        block,
-                        step,
-                        result: jobResult,
-                    }));
-                }
-            }
-            // Record the just-finished helper attempt before re-probing. The gate's next
-            // precheck stays the source of truth for pass/fail, but the helper's own account
-            // (what it did, and for the conflict-resolver which files it left conflicting) is
-            // otherwise discarded here — leaving the gate window with only a bare attempt
-            // count. Capture it so the UI can show what each attempt tried.
-            if (step.gate) {
-                const attempt = recordGateAttempt(step.gate, update.state === 'done'
-                    ? { state: 'done', output: update.result.output ?? null }
-                    : { state: 'failed', error: update.error ?? null }, this.clock.now());
-                step.gate.attemptLog = [...(step.gate.attemptLog ?? []), attempt];
-                // The conflicts gate's precheck carries no failure detail of its own (GitHub
-                // reports mergeability as a single bit), so surface the resolver's account as
-                // the gate's last failure summary. CI's probe already sets a richer summary
-                // (the red checks) — don't clobber it with the fixer's push note.
-                if (step.agentKind === CONFLICTS_AGENT_KIND && attempt.summary) {
-                    step.gate.lastFailureSummary = attempt.summary;
-                }
-            }
-            step.jobId = undefined;
-            step.subtasks = undefined;
-            if (step.gate)
-                step.gate.phase = 'checking';
-            await this.runStateMachine.casPersist(workspaceId, instance);
-            await this.runStateMachine.emitInstance(workspaceId, instance);
-            return { kind: 'awaiting_gate', stepIndex: instance.currentStep };
+            return this.reprobeGateAfterHelper(reprobeGate, { workspaceId, instance, step, update });
         }
         // A `tester` step in its `fixing` phase has a Fixer job in flight, NOT the
         // step's own work: when it finishes (or fails) we drop the handle, return to
@@ -768,6 +642,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)
@@ -775,6 +724,95 @@ export class RunDispatcher {
      * so the caller only persists + emits on a real transition (an idle poll is a no-op).
      * Prior id/url/phase are preserved when a poll omits them (drain-on-read semantics).
      */
+    /**
+     * Fold a running poll's live delta (container status/phase, subtask counts, backend, streamed
+     * follow-ups, env projection) onto `target`, returning whether anything changed. Idempotent for
+     * the set-to-latest folds and correct under CAS retry for the drain-on-read follow-up append —
+     * see the call site in {@link pollAgentJobInner}. A concurrent write that advanced the step (or
+     * superseded the job) makes it a no-op.
+     */
+    async applyRunningFold(target, ctx) {
+        const { jobId, update, workspaceId } = ctx;
+        const s = target.steps[target.currentStep];
+        // The step advanced (or the job was superseded) under a concurrent write — nothing to fold.
+        if (!s || s.jobId !== jobId)
+            return false;
+        let changed = false;
+        if (this.applyContainerRunning(s, update))
+            changed = true;
+        if (this.applySubtaskProgress(s, update.subtasks))
+            changed = true;
+        // The transport reports WHICH backend served the job on the first poll (native host
+        // process vs. sandboxed container) — record it in the run diagnostics.
+        if (this.recordBackendDiagnostics(target, update.backend))
+            changed = true;
+        // Append any forward-looking items the Coder streamed since the last poll so the
+        // Follow-up companion lights up + accrues items LIVE while the container still runs.
+        if (this.followUpGate.appendStreamedFollowUps(s, update.followUps))
+            changed = true;
+        // Refresh the env projection so its status transitions (provisioning→ready→
+        // expired/torn_down) and any error stay live in the run details during the run.
+        if (await this.deployer.attachEnvironmentProjection(workspaceId, target.blockId, s)) {
+            changed = true;
+        }
+        return changed;
+    }
+    /**
+     * A polling gate step's in-flight job is its helper agent (ci-fixer / conflict-resolver / the
+     * human-review fixer), NOT the step's own work: when it finishes (or fails) we don't record a
+     * result or advance — we run any deterministic post-helper bookkeeping hook, record the attempt,
+     * drop the handle, return the gate to `checking`, and re-run the precheck (the helper's push
+     * triggers a fresh CI run / updates mergeability). A helper that failed without pushing leaves the
+     * precheck negative, so the next check re-dispatches (until the attempt budget is spent). Split
+     * from {@link pollAgentJobInner} to keep it under the complexity ceiling.
+     */
+    async reprobeGateAfterHelper(gate, ctx) {
+        const { workspaceId, instance, step, update } = ctx;
+        // A gate may need deterministic GitHub-side bookkeeping to land BEFORE the re-probe
+        // reads it (the human-review gate replies to + RESOLVES the threads it handed the
+        // fixer, so the next probe counts them addressed). Run that side-effect hook first;
+        // it does NOT replace the re-probe (unlike resolveHelperCompletion).
+        if (gate.onHelperComplete && step.gate) {
+            const block = await this.blockRepository.get(workspaceId, instance.blockId);
+            if (block) {
+                const jobResult = update.state === 'done'
+                    ? { state: 'done', result: update.result }
+                    : { state: 'failed', error: update.error ?? null };
+                await this.runInitiatorScope(instance.initiatedBy, () => gate.onHelperComplete({
+                    workspaceId,
+                    instance,
+                    block,
+                    step,
+                    result: jobResult,
+                }));
+            }
+        }
+        // Record the just-finished helper attempt before re-probing. The gate's next
+        // precheck stays the source of truth for pass/fail, but the helper's own account
+        // (what it did, and for the conflict-resolver which files it left conflicting) is
+        // otherwise discarded here — leaving the gate window with only a bare attempt
+        // count. Capture it so the UI can show what each attempt tried.
+        if (step.gate) {
+            const attempt = recordGateAttempt(step.gate, update.state === 'done'
+                ? { state: 'done', output: update.result.output ?? null }
+                : { state: 'failed', error: update.error ?? null }, this.clock.now());
+            step.gate.attemptLog = [...(step.gate.attemptLog ?? []), attempt];
+            // The conflicts gate's precheck carries no failure detail of its own (GitHub
+            // reports mergeability as a single bit), so surface the resolver's account as
+            // the gate's last failure summary. CI's probe already sets a richer summary
+            // (the red checks) — don't clobber it with the fixer's push note.
+            if (step.agentKind === CONFLICTS_AGENT_KIND && attempt.summary) {
+                step.gate.lastFailureSummary = attempt.summary;
+            }
+        }
+        step.jobId = undefined;
+        step.subtasks = undefined;
+        if (step.gate)
+            step.gate.phase = 'checking';
+        await this.runStateMachine.casPersist(workspaceId, instance);
+        await this.runStateMachine.emitInstance(workspaceId, instance);
+        return { kind: 'awaiting_gate', stepIndex: instance.currentStep };
+    }
     applyContainerRunning(step, update) {
         const prev = step.container ?? undefined;
         const next = {
@@ -1026,12 +1064,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
@@ -1072,30 +1105,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
@@ -1103,19 +1113,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
@@ -1150,12 +1148,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
@@ -1171,23 +1164,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
@@ -1228,6 +1205,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