@cat-factory/orchestration 0.177.0 → 0.178.1

package/dist/modules/execution/StepDecisionController.d.ts

@@ -0,0 +1,120 @@
+import { type AgentExecutor, type AgentFailureKind, type Block, type BlockRepository, type Clock, type ExecutionInstance, type ExecutionRepository, type StepReviewComment, type WorkRunner } from '@cat-factory/kernel';
+import { type AgentKindRegistry } from '@cat-factory/agents';
+import type { ReviewEffort } from '@cat-factory/contracts';
+import type { RunStateMachine } from './RunStateMachine.js';
+import type { StepGraph } from './StepGraph.js';
+import type { RunMergePolicy } from './RunMergePolicy.js';
+import type { FinalizeMergeResult } from './MergeResolver.js';
+import type { RunDispatcher } from './RunDispatcher.js';
+/**
+ * Collaborators + bound engine call-backs the {@link StepDecisionController} needs. The five
+ * call-backs (`requireWorkspace` / `requireBlock` / `failRun` / `finalizeMerge`) are bound
+ * {@link ExecutionService} methods, so a decision still runs against the SAME engine state the
+ * inline code did.
+ */
+export interface StepDecisionControllerDeps {
+    agentExecutor: AgentExecutor;
+    agentKindRegistry: AgentKindRegistry;
+    blockRepository: BlockRepository;
+    clock: Clock;
+    executionRepository: ExecutionRepository;
+    mergePolicy: RunMergePolicy;
+    runDispatcher: RunDispatcher;
+    runStateMachine: RunStateMachine;
+    stepGraph: StepGraph;
+    workRunner: WorkRunner;
+    requireWorkspace: (workspaceId: string) => Promise<unknown>;
+    requireBlock: (workspaceId: string, id: string) => Promise<Block>;
+    failRun: (workspaceId: string, executionId: string, message: string, kind?: AgentFailureKind, detail?: string | null, reason?: string | null) => Promise<void>;
+    finalizeMerge: (workspaceId: string, blockId: string) => Promise<FinalizeMergeResult>;
+}
+/**
+ * The HUMAN decision surface on a parked run: resolve a decision, approve / request changes on /
+ * reject a gated proposal, ask the human-review gate for a fix, and merge (or decline to merge)
+ * the PR a finished run left behind. Every one of these is reached from the SPA or the public
+ * API when a person acts on a run the engine deliberately stopped — as opposed to the engine's
+ * own advance path, which is the dispatcher's.
+ *
+ * Extracted from {@link ExecutionService} as a cohesive collaborator (the `RunDispatcher`
+ * controller pattern: a deps object of bound engine call-backs), so the engine service keeps the
+ * run state machine and this file keeps the decisions people make about it. The engine exposes
+ * thin delegates, so no HTTP call site changed.
+ */
+export declare class StepDecisionController {
+    private readonly deps;
+    constructor(deps: StepDecisionControllerDeps);
+    /**
+     * Several gates park on a `step.approval` but are NOT generic prose approvals — they are
+     * driven by their own dedicated surface, never the generic
+     * approve/request-changes/reject resolvers (which would advance the run bypassing the
+     * loop). Guard those resolvers so a stray approve can't short-circuit any of them:
+     * the requirements/clarity review gates, the brainstorms, the human-testing and
+     * visual-confirmation gates, an interview-trait gate, a companion at its rework cap
+     * (`companion.exceeded`), the follow-up companion with undecided items, and a coder
+     * parked on the implementation-fork decision (whose approve would skip the build
+     * dispatch entirely).
+     */
+    private assertNotIterativeGate;
+    /**
+     * Dispatch the `fixer` against the human-review gate's PR branch from a human's freeform
+     * instructions — bypassing the precheck + grace window. Parks a `pendingFix` on the gate step,
+     * consumed on the gate's next poll (see {@link evaluateGate}) which dispatches the fixer with
+     * the instructions folded in. A second request before the first is consumed simply replaces the
+     * pending instructions. Throws when no human-review gate is currently parked.
+     *
+     * The run is re-driven via `workRunner.startRun` so the pending fix is picked up promptly even
+     * when the driver had died (e.g. its durable advance job expired/was evicted before the stale-
+     * run sweeper re-drove it) — `startRun` is idempotent for a live run (the exclusive advance
+     * queue no-ops a duplicate send), so this only has an effect when no driver is currently
+     * polling. A spend-paused run is left paused (it resumes through its own path).
+     */
+    requestHumanReviewFix(workspaceId: string, blockId: string, instructions: string): Promise<ExecutionInstance>; /** Resolve a pending decision; the run's next step lets the agent finish it. */
+    resolveDecision(workspaceId: string, executionId: string, decisionId: string, choice: string): Promise<ExecutionInstance>;
+    /**
+     * Approve a step's gated proposal: the run advances to the next step, carrying
+     * the (optionally human-edited) proposal forward as context. Mirrors
+     * {@link resolveDecision}'s durable-wake but *advances* the pipeline instead of
+     * re-running the step (the step is already done). Idempotent — re-approving an
+     * already-approved gate is a no-op.
+     */
+    approveStep(workspaceId: string, executionId: string, approvalId: string, opts?: {
+        proposal?: string;
+    }): Promise<ExecutionInstance>;
+    /**
+     * Request changes on a step's gated proposal: the same step re-runs with the
+     * human's freeform feedback and/or per-block comments (and its prior proposal)
+     * folded into the agent's context (see {@link AgentContextBuilder}). The run is left
+     * `running` on the same step; on the re-run's completion the gate is raised
+     * afresh. At least one of `feedback`/`comments` is expected (the controller
+     * validates this), but an empty review is harmless — the agent simply re-runs.
+     */
+    requestStepChanges(workspaceId: string, executionId: string, approvalId: string, review: {
+        feedback?: string;
+        comments?: StepReviewComment[];
+    }): Promise<ExecutionInstance>;
+    /**
+     * Reject a step's gated proposal: the run stops entirely. The gate is marked
+     * `rejected` and the run is failed with a dedicated `rejected` failure kind, so
+     * the board surfaces it via the shared failure banner (block → `blocked`) with a
+     * Retry affordance. The parked durable run is woken so it observes the now-terminal
+     * status and stops (the workflow's advance loop no-ops on a non-running run).
+     * Idempotent — rejecting an already-terminal gate is a no-op.
+     */
+    rejectStep(workspaceId: string, executionId: string, approvalId: string, reason?: string): Promise<ExecutionInstance>;
+    /**
+     * Merge an open PR: a block moves from `pr_ready` to `done`. This is the HUMAN merge path —
+     * a `merge_review` / `pipeline_complete` notification act, or the inspector's merge control.
+     *
+     * `reviewEffort` records, in the same call, how much review the PR actually needed. It is
+     * always optional: an untagged merge settles the track record with a null tag and nothing
+     * downstream breaks. The record settle runs AFTER the merge and is best-effort inside the
+     * service, so no part of this feature can fail or block a merge.
+     */
+    mergePr(workspaceId: string, blockId: string, reviewEffort?: ReviewEffort | null): Promise<Block>;
+    /**
+     * Record that a human DECLINED to merge — they dismissed the review card rather than acting on
+     * it, so the class's rollup counts a rejection instead of a forever-`pending_review` row.
+     */
+    recordMergeRejection(workspaceId: string, executionId: string): Promise<void>;
+}
+//# sourceMappingURL=StepDecisionController.d.ts.map

package/dist/modules/execution/StepDecisionController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepDecisionController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/StepDecisionController.ts"],"names":[],"mappings":"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"}

package/dist/modules/execution/StepDecisionController.js

@@ -0,0 +1,347 @@
+import { ConflictError, NotFoundError, ValidationError, assertFound, } from '@cat-factory/kernel';
+import { companionTargets, hasTrait, INTERVIEW_GATE_TRAIT, isCompanionKind, } from '@cat-factory/agents';
+import { isAsyncAgentExecutor } from '@cat-factory/kernel';
+import { ARCHITECTURE_BRAINSTORM_AGENT_KIND, CLARITY_REVIEW_AGENT_KIND, HUMAN_REVIEW_AGENT_KIND, HUMAN_TEST_AGENT_KIND, REQUIREMENTS_BRAINSTORM_AGENT_KIND, REQUIREMENTS_REVIEW_AGENT_KIND, VISUAL_CONFIRM_AGENT_KIND, } from './ci.logic.js';
+/**
+ * The HUMAN decision surface on a parked run: resolve a decision, approve / request changes on /
+ * reject a gated proposal, ask the human-review gate for a fix, and merge (or decline to merge)
+ * the PR a finished run left behind. Every one of these is reached from the SPA or the public
+ * API when a person acts on a run the engine deliberately stopped — as opposed to the engine's
+ * own advance path, which is the dispatcher's.
+ *
+ * Extracted from {@link ExecutionService} as a cohesive collaborator (the `RunDispatcher`
+ * controller pattern: a deps object of bound engine call-backs), so the engine service keeps the
+ * run state machine and this file keeps the decisions people make about it. The engine exposes
+ * thin delegates, so no HTTP call site changed.
+ */
+export class StepDecisionController {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Several gates park on a `step.approval` but are NOT generic prose approvals — they are
+     * driven by their own dedicated surface, never the generic
+     * approve/request-changes/reject resolvers (which would advance the run bypassing the
+     * loop). Guard those resolvers so a stray approve can't short-circuit any of them:
+     * the requirements/clarity review gates, the brainstorms, the human-testing and
+     * visual-confirmation gates, an interview-trait gate, a companion at its rework cap
+     * (`companion.exceeded`), the follow-up companion with undecided items, and a coder
+     * parked on the implementation-fork decision (whose approve would skip the build
+     * dispatch entirely).
+     */
+    assertNotIterativeGate(step) {
+        if (step.agentKind === REQUIREMENTS_REVIEW_AGENT_KIND) {
+            throw new ConflictError('Resolve the requirements review through its review window, not the approval gate');
+        }
+        if (step.agentKind === CLARITY_REVIEW_AGENT_KIND) {
+            throw new ConflictError('Resolve the clarity review through its review window, not the approval gate');
+        }
+        if (step.agentKind === REQUIREMENTS_BRAINSTORM_AGENT_KIND ||
+            step.agentKind === ARCHITECTURE_BRAINSTORM_AGENT_KIND) {
+            throw new ConflictError('Resolve the brainstorm through its brainstorm window, not the approval gate');
+        }
+        if (step.agentKind === HUMAN_TEST_AGENT_KIND) {
+            throw new ConflictError('Resolve the human-testing gate through its window (confirm / request a fix), not the approval gate');
+        }
+        if (step.agentKind === VISUAL_CONFIRM_AGENT_KIND) {
+            throw new ConflictError('Resolve the visual-confirmation gate through its window (approve / request a fix), not the approval gate');
+        }
+        if (hasTrait(step.agentKind, INTERVIEW_GATE_TRAIT, this.deps.agentKindRegistry)) {
+            throw new ConflictError('Resolve the interview through its interview window, not the approval gate');
+        }
+        if (step.companion?.exceeded) {
+            throw new ConflictError('Resolve this companion review through its iteration-cap prompt, not the approval gate');
+        }
+        if (step.followUps?.enabled && step.followUps.items.some((i) => i.status === 'pending')) {
+            throw new ConflictError('Resolve the follow-up companion through its window (file / send back / answer / dismiss), not the approval gate');
+        }
+        if (step.forkDecision?.status === 'awaiting_choice' ||
+            step.forkDecision?.status === 'answering') {
+            // Approving here would advance the run PAST the coder step with the build never run
+            // (the park sits between the proposer and the Coder dispatch).
+            throw new ConflictError('Resolve the implementation-fork decision through its fork window (choose an approach), not the approval gate');
+        }
+    }
+    /**
+     * Dispatch the `fixer` against the human-review gate's PR branch from a human's freeform
+     * instructions — bypassing the precheck + grace window. Parks a `pendingFix` on the gate step,
+     * consumed on the gate's next poll (see {@link evaluateGate}) which dispatches the fixer with
+     * the instructions folded in. A second request before the first is consumed simply replaces the
+     * pending instructions. Throws when no human-review gate is currently parked.
+     *
+     * The run is re-driven via `workRunner.startRun` so the pending fix is picked up promptly even
+     * when the driver had died (e.g. its durable advance job expired/was evicted before the stale-
+     * run sweeper re-drove it) — `startRun` is idempotent for a live run (the exclusive advance
+     * queue no-ops a duplicate send), so this only has an effect when no driver is currently
+     * polling. A spend-paused run is left paused (it resumes through its own path).
+     */
+    async requestHumanReviewFix(workspaceId, blockId, instructions) {
+        const block = await this.deps.blockRepository.get(workspaceId, blockId);
+        if (!block?.executionId) {
+            throw new ConflictError('No human-review gate is currently awaiting input');
+        }
+        // Optimistic-concurrency write: parking the `pendingFix` can race the gate's own poll
+        // (the durable driver advancing the run), so re-read + re-apply on fresh state instead
+        // of clobbering — the lost-update fix, same path as resolveDecision. The validation runs
+        // inside the mutation so it sees the run as it stands at write time.
+        const instance = await this.deps.runStateMachine.mutateInstance(workspaceId, block.executionId, (inst) => {
+            const step = inst.steps[inst.currentStep];
+            if (!step || step.agentKind !== HUMAN_REVIEW_AGENT_KIND || !step.gate) {
+                throw new ConflictError('No human-review gate is currently awaiting input');
+            }
+            // The fix is consumed by evaluateGate's pendingFix branch, which dispatches the fixer
+            // ONLY when the gate's provider is wired AND there is an async executor to escalate to.
+            // Reject up front when neither holds, instead of silently parking a pendingFix the gate
+            // would discard on its pass-through (an unwired gate advances) — the caller must see the
+            // failure, not a 200.
+            const gate = this.deps.runDispatcher.gateFor(step.agentKind);
+            if (!gate?.wired() || !isAsyncAgentExecutor(this.deps.agentExecutor)) {
+                throw new ConflictError('The human-review gate cannot dispatch a fix on this deployment (no review provider or async executor configured)');
+            }
+            step.gate.pendingFix = { instructions, at: this.deps.clock.now() };
+            // Re-arm a decision-parked run so the re-driven loop polls instead of no-oping; a spend-
+            // paused run stays paused.
+            if (inst.status === 'blocked')
+                inst.status = 'running';
+        });
+        await this.deps.runStateMachine.emitInstance(workspaceId, instance);
+        // Ensure a driver is active to consume the pending fix (idempotent for a live run).
+        if (instance.status === 'running') {
+            await this.deps.workRunner.startRun(workspaceId, instance.id);
+        }
+        return instance;
+    } /** Resolve a pending decision; the run's next step lets the agent finish it. */
+    async resolveDecision(workspaceId, executionId, decisionId, choice) {
+        await this.deps.requireWorkspace(workspaceId);
+        // Optimistic-concurrency write: a second resolve (double-click) or a racing driver
+        // poll can't clobber the chosen decision — the loser re-reads and re-applies.
+        const instance = await this.deps.runStateMachine.mutateInstance(workspaceId, executionId, async (inst) => {
+            const step = inst.steps.find((s) => s.decision?.id === decisionId);
+            if (!step || !step.decision)
+                throw new NotFoundError('Decision', decisionId);
+            step.decision.chosen = choice;
+            this.deps.stepGraph.startStep(step);
+            if (inst.status === 'blocked')
+                inst.status = 'running';
+            await this.deps.runStateMachine.updateBlockProgress(workspaceId, inst, 'in_progress');
+        });
+        // Wake the parked durable run, if any. The DB write above remains the source
+        // of truth (so the backstop sweeper can still re-drive it); the signal is an
+        // optimisation that lets the workflow continue immediately.
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, decisionId, choice);
+        await this.deps.runStateMachine.emitInstance(workspaceId, instance);
+        return instance;
+    }
+    /**
+     * Approve a step's gated proposal: the run advances to the next step, carrying
+     * the (optionally human-edited) proposal forward as context. Mirrors
+     * {@link resolveDecision}'s durable-wake but *advances* the pipeline instead of
+     * re-running the step (the step is already done). Idempotent — re-approving an
+     * already-approved gate is a no-op.
+     */
+    async approveStep(workspaceId, executionId, approvalId, opts = {}) {
+        await this.deps.requireWorkspace(workspaceId);
+        // Optimistic-concurrency write like resolveDecision/requestStepChanges: an approve
+        // holding a stale snapshot (a racing reject, a driver poll, a terminal transition)
+        // must re-read and re-validate rather than blind-write — otherwise it can resurrect
+        // a run another writer already failed. The advance's in-memory half runs inside the
+        // CAS; the non-idempotent side effects (block writes, driver signal, emit) run once
+        // after, on the winning state.
+        let stepIndex = -1;
+        let alreadyApproved = false;
+        const instance = await this.deps.runStateMachine.mutateInstance(workspaceId, executionId, (inst) => {
+            alreadyApproved = false;
+            stepIndex = inst.steps.findIndex((s) => s.approval?.id === approvalId);
+            const step = inst.steps[stepIndex];
+            if (!step || !step.approval)
+                throw new NotFoundError('Approval', approvalId);
+            this.assertNotIterativeGate(step);
+            if (step.approval.status === 'approved') {
+                alreadyApproved = true;
+                return;
+            }
+            if (step.approval.status === 'rejected') {
+                throw new ConflictError(`Approval '${approvalId}' was rejected`);
+            }
+            if (inst.status === 'failed' || inst.status === 'done') {
+                throw new ConflictError(`Execution '${executionId}' is already ${inst.status}`);
+            }
+            // A human edit to the proposal replaces the agent's text, so the revised
+            // proposal is what downstream steps read (via priorOutputs). That only holds when the
+            // output IS the agent's work product: a step whose output is a RENDERING of an
+            // already-ingested artifact (the spec doc, the blueprint tree, the initiative plan —
+            // see `reviewableArtifactOutput`) would take the edit into `step.output` while the
+            // committed artifact stayed the ingested one, so the correction silently reaches
+            // nothing. Refuse rather than accept-and-drop; the reviewer's route is "request
+            // changes", which re-runs the producer with the correction as feedback.
+            if (opts.proposal !== undefined) {
+                if (step.outputIsRendered) {
+                    throw new ValidationError("This step's output is a rendering of the artifact it already produced, so edits " +
+                        'to it cannot change that artifact. Request changes instead — the step re-runs ' +
+                        'with your feedback.', { reason: 'proposal_not_editable' });
+                }
+                step.output = opts.proposal;
+                step.approval.proposal = opts.proposal;
+            }
+            step.approval.status = 'approved';
+            // A gate is never raised on the final step, but the shared advance stays defensive.
+            this.deps.runStateMachine.advanceRunPastGate(inst, stepIndex);
+        });
+        if (alreadyApproved)
+            return instance;
+        await this.deps.runStateMachine.settleAdvancedGate(workspaceId, instance, stepIndex);
+        return instance;
+    }
+    /**
+     * Request changes on a step's gated proposal: the same step re-runs with the
+     * human's freeform feedback and/or per-block comments (and its prior proposal)
+     * folded into the agent's context (see {@link AgentContextBuilder}). The run is left
+     * `running` on the same step; on the re-run's completion the gate is raised
+     * afresh. At least one of `feedback`/`comments` is expected (the controller
+     * validates this), but an empty review is harmless — the agent simply re-runs.
+     */
+    async requestStepChanges(workspaceId, executionId, approvalId, review) {
+        await this.deps.requireWorkspace(workspaceId);
+        // Optimistic-concurrency write: two concurrent change-requests on the same gate
+        // (the documented double-submit) can't both dispatch a re-run — the loser re-reads,
+        // sees `changes_requested`, and is rejected below instead of clobbering.
+        const instance = await this.deps.runStateMachine.mutateInstance(workspaceId, executionId, (inst) => {
+            const step = inst.steps.find((s) => s.approval?.id === approvalId);
+            if (!step || !step.approval)
+                throw new NotFoundError('Approval', approvalId);
+            this.assertNotIterativeGate(step);
+            if (step.approval.status === 'approved') {
+                throw new ConflictError(`Approval '${approvalId}' is already approved`);
+            }
+            if (step.approval.status === 'rejected') {
+                throw new ConflictError(`Approval '${approvalId}' was rejected`);
+            }
+            // A re-run is already in flight (and will raise a fresh gate on completion);
+            // acting on this now-stale gate id would dispatch duplicate work.
+            if (step.approval.status === 'changes_requested') {
+                throw new ConflictError(`Approval '${approvalId}' is already being re-run`);
+            }
+            const stepIndex = inst.steps.findIndex((s) => s.approval?.id === approvalId);
+            step.approval.status = 'changes_requested';
+            step.approval.feedback = review.feedback;
+            step.approval.comments = review.comments?.length ? review.comments : undefined;
+            // A companion's gate reviews the PRODUCER's output, not the companion's own work:
+            // requesting changes here must re-run the producer (with the human's feedback
+            // folded in) and re-grade, NOT re-run the companion. Redirect the rework to the
+            // nearest preceding step of one of the companion's target kinds.
+            if (isCompanionKind(step.agentKind)) {
+                const targets = companionTargets(step.agentKind);
+                let producerIndex = -1;
+                for (let i = stepIndex - 1; i >= 0; i--) {
+                    if (targets.includes(inst.steps[i].agentKind)) {
+                        producerIndex = i;
+                        break;
+                    }
+                }
+                const producer = producerIndex >= 0 ? inst.steps[producerIndex] : undefined;
+                if (producer) {
+                    // Re-run the producer (with the human's feedback) and every step up to and
+                    // 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.deps.stepGraph.rerunProducerThrough(inst, producerIndex, stepIndex, {
+                        previousProposal,
+                        feedback: review.feedback ?? '',
+                        ...(review.comments?.length ? { comments: review.comments } : {}),
+                    });
+                    if (inst.status === 'blocked')
+                        inst.status = 'running';
+                    return;
+                }
+            }
+            // Drop the live job handle so the re-run dispatches fresh work rather than
+            // re-attaching to the finished job (async steps); inline steps ignore this.
+            step.jobId = undefined;
+            // A requested re-run is a fresh execution: clear the prior timing so the next
+            // start/finish times this attempt rather than spanning the human gate wait.
+            step.startedAt = null;
+            step.finishedAt = null;
+            this.deps.stepGraph.startStep(step);
+            if (inst.status === 'blocked')
+                inst.status = 'running';
+        });
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, approvalId, 'changes_requested');
+        await this.deps.runStateMachine.emitInstance(workspaceId, instance);
+        return instance;
+    }
+    /**
+     * Reject a step's gated proposal: the run stops entirely. The gate is marked
+     * `rejected` and the run is failed with a dedicated `rejected` failure kind, so
+     * the board surfaces it via the shared failure banner (block → `blocked`) with a
+     * Retry affordance. The parked durable run is woken so it observes the now-terminal
+     * status and stops (the workflow's advance loop no-ops on a non-running run).
+     * Idempotent — rejecting an already-terminal gate is a no-op.
+     */
+    async rejectStep(workspaceId, executionId, approvalId, reason) {
+        await this.deps.requireWorkspace(workspaceId);
+        // Optimistic-concurrency write: a reject racing the durable driver (or a concurrent
+        // resolve/request-changes on the same gate) re-reads and re-applies instead of
+        // clobbering the other writer — the lost-update fix, same as resolveDecision.
+        let alreadyRejected = false;
+        const instance = await this.deps.runStateMachine.mutateInstance(workspaceId, executionId, (inst) => {
+            const step = inst.steps.find((s) => s.approval?.id === approvalId);
+            if (!step || !step.approval)
+                throw new NotFoundError('Approval', approvalId);
+            this.assertNotIterativeGate(step);
+            if (step.approval.status === 'approved') {
+                throw new ConflictError(`Approval '${approvalId}' is already approved`);
+            }
+            // A re-run is in flight; this gate id is stale (a fresh one is raised on its
+            // completion). Reject the current gate via that fresh id, not this one.
+            if (step.approval.status === 'changes_requested') {
+                throw new ConflictError(`Approval '${approvalId}' is being re-run`);
+            }
+            // Already rejected (and the run already failed): leave it as-is and skip failRun below.
+            if (step.approval.status === 'rejected') {
+                alreadyRejected = true;
+                return;
+            }
+            step.approval.status = 'rejected';
+            if (reason)
+                step.approval.feedback = reason;
+        });
+        if (alreadyRejected)
+            return instance;
+        const message = reason
+            ? `A reviewer rejected the proposal: ${reason}`
+            : 'A reviewer rejected the proposal, stopping the run.';
+        // failRun persists the terminal failure + flips the block to `blocked` and emits.
+        await this.deps.failRun(workspaceId, executionId, message, 'rejected');
+        // Wake the parked durable run; it re-reads the now-terminal status and stops.
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, approvalId, 'rejected');
+        return assertFound(await this.deps.executionRepository.get(workspaceId, executionId), 'Execution', executionId);
+    }
+    /**
+     * Merge an open PR: a block moves from `pr_ready` to `done`. This is the HUMAN merge path —
+     * a `merge_review` / `pipeline_complete` notification act, or the inspector's merge control.
+     *
+     * `reviewEffort` records, in the same call, how much review the PR actually needed. It is
+     * always optional: an untagged merge settles the track record with a null tag and nothing
+     * downstream breaks. The record settle runs AFTER the merge and is best-effort inside the
+     * service, so no part of this feature can fail or block a merge.
+     */
+    async mergePr(workspaceId, blockId, reviewEffort) {
+        await this.deps.requireWorkspace(workspaceId);
+        const block = await this.deps.requireBlock(workspaceId, blockId);
+        if (block.status !== 'pr_ready') {
+            throw new ConflictError(`Block '${blockId}' has no PR awaiting merge`, 'no_pr_to_merge');
+        }
+        await this.deps.finalizeMerge(workspaceId, blockId);
+        await this.deps.mergePolicy.recordHumanMerge(workspaceId, blockId, reviewEffort);
+        return this.deps.requireBlock(workspaceId, blockId);
+    }
+    /**
+     * Record that a human DECLINED to merge — they dismissed the review card rather than acting on
+     * it, so the class's rollup counts a rejection instead of a forever-`pending_review` row.
+     */
+    recordMergeRejection(workspaceId, executionId) {
+        return this.deps.mergePolicy.recordRejection(workspaceId, executionId);
+    }
+}
+//# sourceMappingURL=StepDecisionController.js.map

package/dist/modules/execution/StepDecisionController.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepDecisionController.js","sourceRoot":"","sources":["../../../src/modules/execution/StepDecisionController.ts"],"names":[],"mappings":"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"}

package/dist/modules/execution/dispatchPromptSettings.d.ts

@@ -0,0 +1,43 @@
+import type { AgentPromptRepository, Logger, PipelineStep, WorkspaceAgentSettingsRepository } from '@cat-factory/kernel';
+import type { AgentKindRegistry } from '@cat-factory/agents';
+/** The narrow slice of the builder's dependencies these two resolvers need. */
+export interface DispatchPromptSettingsDeps {
+    agentKindRegistry: AgentKindRegistry;
+    /** The append-only per-workspace prompt log. Absent ⇒ the override feature is not wired. */
+    agentPrompts?: AgentPromptRepository;
+    /** The per-workspace, per-kind generation settings. Absent ⇒ the feature is not wired. */
+    agentSettings?: WorkspaceAgentSettingsRepository;
+    logger?: Logger;
+}
+/**
+ * The base system prompt this dispatch replaces the shipped one with, or undefined to run the
+ * shipped one. Two tiers converge here — the deployment's registered agent-kind VARIANT for this
+ * step and the WORKSPACE's edited prompt for the kind — because they are the same unit of text.
+ *
+ * The head revision's `text` is `null` when the workspace deliberately went BACK to the built-in —
+ * a real state, distinct from never having edited the kind, which is why it is recorded rather than
+ * deleted. Both resolve to "no override" here, so a revert keeps tracking the shipped prompt as the
+ * product bumps it instead of pinning a stale copy.
+ *
+ * MUTATES the step to pin what it resolved (`promptRevision`, `promptVariant`), because neither can
+ * be re-derived afterwards: the prompt log is append-only, so re-reading it at any later point — a
+ * Kaizen grading, a debug read, a post-mortem — would answer about whatever landed since. The
+ * VARIANT is pinned for a second reason: `stepOptions.agentVariantId` is what the pipeline ASKED
+ * for, and a workspace override or a withdrawal can mean the variant's text never reached the
+ * prompt, so only a pin taken HERE can answer what the step actually ran under.
+ */
+export declare function resolveDispatchSystemPrompt(deps: DispatchPromptSettingsDeps, workspaceId: string, agentKind: string, step: PipelineStep): Promise<{
+    systemPromptOverride?: string;
+}>;
+/**
+ * The output-token ceiling this dispatch runs under, or undefined to run the deployment routing
+ * default.
+ *
+ * NARROWEST TIER WINS: the step's own `stepOptions.maxOutputTokens` beats the workspace's per-kind
+ * setting, which beats the deployment routing ceiling. The step value is read WITHOUT touching the
+ * repository, so a pipeline that pins its own budget costs no query.
+ */
+export declare function resolveDispatchMaxOutputTokens(deps: DispatchPromptSettingsDeps, workspaceId: string, agentKind: string, step: PipelineStep): Promise<{
+    maxOutputTokens?: number;
+}>;
+//# sourceMappingURL=dispatchPromptSettings.d.ts.map

package/dist/modules/execution/dispatchPromptSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchPromptSettings.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/dispatchPromptSettings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,MAAM,EACN,YAAY,EACZ,gCAAgC,EACjC,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAsB5D,+EAA+E;AAC/E,MAAM,WAAW,0BAA0B;IACzC,iBAAiB,EAAE,iBAAiB,CAAA;IACpC,4FAA4F;IAC5F,YAAY,CAAC,EAAE,qBAAqB,CAAA;IACpC,0FAA0F;IAC1F,aAAa,CAAC,EAAE,gCAAgC,CAAA;IAChD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,2BAA2B,CAC/C,IAAI,EAAE,0BAA0B,EAChC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C5C;AAED;;;;;;;GAOG;AACH,wBAAsB,8BAA8B,CAClD,IAAI,EAAE,0BAA0B,EAChC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC;IAAE,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAKvC"}

package/dist/modules/execution/dispatchPromptSettings.js

@@ -0,0 +1,76 @@
+import { applyAgentVariant, shippedBasePromptFor } from '@cat-factory/agents';
+/**
+ * The base system prompt this dispatch replaces the shipped one with, or undefined to run the
+ * shipped one. Two tiers converge here — the deployment's registered agent-kind VARIANT for this
+ * step and the WORKSPACE's edited prompt for the kind — because they are the same unit of text.
+ *
+ * The head revision's `text` is `null` when the workspace deliberately went BACK to the built-in —
+ * a real state, distinct from never having edited the kind, which is why it is recorded rather than
+ * deleted. Both resolve to "no override" here, so a revert keeps tracking the shipped prompt as the
+ * product bumps it instead of pinning a stale copy.
+ *
+ * MUTATES the step to pin what it resolved (`promptRevision`, `promptVariant`), because neither can
+ * be re-derived afterwards: the prompt log is append-only, so re-reading it at any later point — a
+ * Kaizen grading, a debug read, a post-mortem — would answer about whatever landed since. The
+ * VARIANT is pinned for a second reason: `stepOptions.agentVariantId` is what the pipeline ASKED
+ * for, and a workspace override or a withdrawal can mean the variant's text never reached the
+ * prompt, so only a pin taken HERE can answer what the step actually ran under.
+ */
+export async function resolveDispatchSystemPrompt(deps, workspaceId, agentKind, step) {
+    const head = await deps.agentPrompts?.head(workspaceId, agentKind);
+    // Cleared, not left stale: a re-dispatch after the workspace reverted must not keep reporting
+    // the revision the previous attempt ran under.
+    step.promptRevision = head?.text ? head.revision : undefined;
+    // The variant applies only when the kind being dispatched IS the step's own — a helper dispatched
+    // off this step (a gate's fixer, the fork proposer) is a different agent and must not inherit the
+    // step's alternate prompt. Same rule as `followUpCompanion`.
+    const variantId = agentKind === step.agentKind ? step.stepOptions?.agentVariantId : undefined;
+    const variant = variantId ? deps.agentKindRegistry.variant(variantId) : undefined;
+    // A variant the deployment has since withdrawn: the step runs the SHIPPED prompt, which is the
+    // safe disposition, but it is not what the pipeline asked for — so say so rather than let a step
+    // quietly stop being the variation someone configured.
+    if (variantId && !variant) {
+        deps.logger?.warn('Agent kind variant is not registered; running the shipped prompt', {
+            agentKind,
+            variantId,
+        });
+    }
+    const { prompt, applied, fingerprint } = applyAgentVariant(
+    // Only paid for when a variant is actually selected; the shipped prompt is what its addition
+    // folds onto and what its replacement is measured against.
+    variant ? shippedBasePromptFor(agentKind, deps.agentKindRegistry) : '', variant, head?.text ?? undefined);
+    // The workspace out-ranks the deployment on the same unit of text, so its edit DISPLACES a
+    // variant's replacement. That is the intended precedence, but it is a silent loss of something a
+    // deployment configured in code — the one disposition here with no other symptom — so it is
+    // reported at the fold, exactly as a withdrawal is above.
+    if (applied === 'superseded' || applied === 'addition-only') {
+        deps.logger?.warn("Workspace prompt override displaced the agent variant's own prompt for this dispatch", { agentKind, variantId, promptRevision: step.promptRevision, applied });
+    }
+    // What the dispatch DID with the step's selected variant, so a later reader is never told a step
+    // ran a variation whose text never reached it. Cleared, not left stale, for the same reason
+    // `promptRevision` is: a re-dispatch resolves it afresh.
+    step.promptVariant = variantId
+        ? {
+            id: variantId,
+            applied: variant ? applied : 'withdrawn',
+            ...(fingerprint ? { fingerprint } : {}),
+        }
+        : undefined;
+    return prompt ? { systemPromptOverride: prompt } : {};
+}
+/**
+ * The output-token ceiling this dispatch runs under, or undefined to run the deployment routing
+ * default.
+ *
+ * NARROWEST TIER WINS: the step's own `stepOptions.maxOutputTokens` beats the workspace's per-kind
+ * setting, which beats the deployment routing ceiling. The step value is read WITHOUT touching the
+ * repository, so a pipeline that pins its own budget costs no query.
+ */
+export async function resolveDispatchMaxOutputTokens(deps, workspaceId, agentKind, step) {
+    const fromStep = step.stepOptions?.maxOutputTokens;
+    if (fromStep != null)
+        return { maxOutputTokens: fromStep };
+    const configured = await deps.agentSettings?.get(workspaceId, agentKind);
+    return configured?.maxOutputTokens != null ? { maxOutputTokens: configured.maxOutputTokens } : {};
+}
+//# sourceMappingURL=dispatchPromptSettings.js.map

package/dist/modules/execution/dispatchPromptSettings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatchPromptSettings.js","sourceRoot":"","sources":["../../../src/modules/execution/dispatchPromptSettings.ts"],"names":[],"mappings":"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"}