@cat-factory/orchestration 0.143.1 → 0.145.0

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

@@ -0,0 +1,42 @@
+import type { JudgeAssessor, JudgeSubject, ModelProvider, ModelProviderResolver, ModelRef } from '@cat-factory/kernel';
+import { type ResolveBlockRunContext } from '../../inlineScope.js';
+/** What the inline assessor needs to resolve its model and reach the provider. */
+export interface JudgeServiceDeps {
+    /** Resolve a ModelProvider for a workspace's credential scope (preferred). */
+    modelProviderResolver?: ModelProviderResolver;
+    /** Static provider (e.g. a fake in tests) used when no resolver is set. */
+    modelProvider?: ModelProvider;
+    /** Routing-default model ref when the block pins none. */
+    modelRef?: ModelRef;
+    /** Resolve a block's selected model id to a ref (the deployment-aware resolver). */
+    resolveBlockModel?: (modelId: string | undefined) => ModelRef | undefined;
+    /** Keep an ambient-eligible harness ref inline (local mode) instead of degrading it. */
+    runsInline?: (ref: ModelRef) => boolean;
+    /** Resolve the workspace's per-agent-kind default model id (block pins none). */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string, modelPresetId?: string) => Promise<string | undefined>;
+    /** Resolve the block's run/execution + initiator, folded into the inline model scope. */
+    resolveRunContext?: ResolveBlockRunContext;
+}
+export declare class JudgeService implements JudgeAssessor {
+    private readonly deps;
+    constructor(deps: JudgeServiceDeps);
+    /** Whether an assessment can run (a provider AND a routing default are wired). */
+    get enabled(): boolean;
+    /**
+     * Run ONE assessment against the rubric in force. Returns the raw extracted JSON value (the
+     * judge's registered parser owns the shape) plus the model that produced it.
+     *
+     * Throws {@link ValidationError} on an unresolved model, a failed generation, or a reply
+     * with no JSON object in it. The engine catches that and records a FAILING verdict rather
+     * than crashing the run — an assessment that could not be read must never be mistaken for a
+     * clean one.
+     */
+    assess(subject: JudgeSubject): Promise<{
+        verdict: unknown;
+        model: string;
+    }>;
+    private resolveModel;
+    /** Block pin > workspace per-kind default > routing default (subscription refs degrade inline). */
+    private modelFor;
+}
+//# sourceMappingURL=JudgeService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"JudgeService.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/JudgeService.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,aAAa,EACb,YAAY,EACZ,aAAa,EACb,qBAAqB,EACrB,QAAQ,EACT,MAAM,qBAAqB,CAAA;AAa5B,OAAO,EAAE,KAAK,sBAAsB,EAAoB,MAAM,sBAAsB,CAAA;AAoBpF,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,qBAAqB,CAAC,EAAE,qBAAqB,CAAA;IAC7C,2EAA2E;IAC3E,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,oFAAoF;IACpF,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,KAAK,QAAQ,GAAG,SAAS,CAAA;IACzE,wFAAwF;IACxF,UAAU,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,OAAO,CAAA;IACvC,iFAAiF;IACjF,4BAA4B,CAAC,EAAE,CAC7B,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,aAAa,CAAC,EAAE,MAAM,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;IAChC,yFAAyF;IACzF,iBAAiB,CAAC,EAAE,sBAAsB,CAAA;CAC3C;AAED,qBAAa,YAAa,YAAW,aAAa;IACpC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,gBAAgB,EAAI;IAEvD,kFAAkF;IAClF,IAAI,OAAO,IAAI,OAAO,CAErB;IAED;;;;;;;;OAQG;IACG,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAmChF;YAEa,YAAY;IAa1B,mGAAmG;YACrF,QAAQ;CAgBvB"}

package/dist/modules/execution/JudgeService.js

@@ -0,0 +1,78 @@
+import { generateText } from 'ai';
+import { extractJson, inlineModelRef, resolveScopedModelProvider, ValidationError, } from '@cat-factory/kernel';
+import { catFactoryObservability, JUDGE_AGENT_KIND, JUDGE_SYSTEM_PROMPT, renderJudgePrompt, } from '@cat-factory/agents';
+import { scopeForBlockRun } from '../../inlineScope.js';
+export class JudgeService {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Whether an assessment can run (a provider AND a routing default are wired). */
+    get enabled() {
+        return (!!this.deps.modelProviderResolver || !!this.deps.modelProvider) && !!this.deps.modelRef;
+    }
+    /**
+     * Run ONE assessment against the rubric in force. Returns the raw extracted JSON value (the
+     * judge's registered parser owns the shape) plus the model that produced it.
+     *
+     * Throws {@link ValidationError} on an unresolved model, a failed generation, or a reply
+     * with no JSON object in it. The engine catches that and records a FAILING verdict rather
+     * than crashing the run — an assessment that could not be read must never be mistaken for a
+     * clean one.
+     */
+    async assess(subject) {
+        const { modelProvider, ref } = await this.resolveModel(subject.workspaceId, subject.block);
+        let text;
+        try {
+            const result = await generateText({
+                model: modelProvider.resolve(ref),
+                system: JUDGE_SYSTEM_PROMPT,
+                prompt: renderJudgePrompt(subject),
+                // Judgement should be reproducible for the same evidence: a rubric verdict that moves
+                // between identical runs is not a policy, it's noise.
+                temperature: 0,
+                maxOutputTokens: 2000,
+                providerOptions: catFactoryObservability({
+                    agentKind: JUDGE_AGENT_KIND,
+                    workspaceId: subject.workspaceId,
+                }),
+            });
+            text = result.text;
+        }
+        catch (e) {
+            throw new ValidationError(`The judge assessment (${ref.provider}:${ref.model}) failed: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const verdict = extractJson(text);
+        if (verdict === null || typeof verdict !== 'object') {
+            // An empty visible reply means the model answered only into its private reasoning
+            // channel (seen on some reasoning models); a non-JSON reply means it ignored the
+            // contract. Either way there is nothing to score.
+            throw new ValidationError(`The judge assessment (${ref.provider}:${ref.model}) returned no JSON verdict`);
+        }
+        return { verdict, model: `${ref.provider}:${ref.model}` };
+    }
+    async resolveModel(workspaceId, block) {
+        const scope = await scopeForBlockRun(workspaceId, block, this.deps.resolveRunContext);
+        const modelProvider = await resolveScopedModelProvider(scope, this.deps);
+        const ref = await this.modelFor(workspaceId, block);
+        if (!modelProvider || !ref) {
+            throw new ValidationError('No model is configured for the judge assessment');
+        }
+        return { modelProvider, ref };
+    }
+    /** Block pin > workspace per-kind default > routing default (subscription refs degrade inline). */
+    async modelFor(workspaceId, block) {
+        const fallback = this.deps.modelRef;
+        const runsInline = this.deps.runsInline;
+        const resolve = (ref) => inlineModelRef(ref, fallback ?? ref, runsInline ? { runsInline } : {});
+        const fromBlock = this.deps.resolveBlockModel?.(block.modelId);
+        if (fromBlock)
+            return resolve(fromBlock);
+        const defaultId = await this.deps.resolveWorkspaceModelDefault?.(workspaceId, JUDGE_AGENT_KIND, block.modelPresetId);
+        const fromDefault = this.deps.resolveBlockModel?.(defaultId);
+        if (fromDefault)
+            return resolve(fromDefault);
+        return fallback;
+    }
+}
+//# sourceMappingURL=JudgeService.js.map

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

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

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

@@ -0,0 +1,116 @@
+import type { AgentRunResult, Block, Clock, ExecutionInstance, ExecutionRepository, JudgeAssessor, JudgeContext, JudgeDefinition, JudgeRegistry, JudgeStepState, PipelineStep, ResolveJudgeInput, RaiseNotificationInput, RiskPolicy, RunInitiatorScope, WorkRunner } from '@cat-factory/kernel';
+import type { AdvanceResult } from './advance.js';
+import type { FragmentBodyResolver } from './AgentContextBuilder.js';
+import type { RunStateMachine } from './RunStateMachine.js';
+import type { StepGraph } from './StepGraph.js';
+/** What the judge driver needs beyond the shared run state-machine spine. */
+export interface JudgeStepControllerDeps {
+    /** The app-owned registry the composition root injected (deployment-registered judges). */
+    judgeRegistry: JudgeRegistry;
+    /**
+     * The verdict producer. Absent / `enabled === false` ⇒ every judge step is a pass-through.
+     * The engine's default is the inline `JudgeService`; conformance injects a deterministic fake.
+     */
+    judgeAssessor?: JudgeAssessor;
+    executionRepository: ExecutionRepository;
+    /** The async instance/block spine (park/advance/persist/emit/notify/fail). */
+    stateMachine: RunStateMachine;
+    /** The pure step mutators (start/finish/reset/rewind a step). */
+    stepGraph: StepGraph;
+    workRunner: WorkRunner;
+    clock: Clock;
+    runInitiatorScope: RunInitiatorScope;
+    /** Raise a human-actionable card (the `judge_review` park notification). */
+    raiseNotification: (workspaceId: string, input: RaiseNotificationInput) => Promise<void>;
+    /** The task's resolved merge preset — the source of the threshold + bounce budget. */
+    resolveRiskPolicy: (workspaceId: string, block: Block) => Promise<Pick<RiskPolicy, 'judgeMinScore' | 'judgeMaxBounces'>>;
+    /**
+     * The prompt-fragment library, used for ONE thing: resolving a rubric's per-workspace
+     * override body. Absent (no library configured) ⇒ the registration's default rubric, which
+     * is exactly the behaviour a stock deployment gets.
+     */
+    fragmentResolver?: FragmentBodyResolver;
+    /** The engine's completion spine, so a passing judge finishes + advances like any step. */
+    recordStepResult: (workspaceId: string, instance: ExecutionInstance, step: PipelineStep, isFinalStep: boolean, result: AgentRunResult) => Promise<AdvanceResult>;
+    /** The judge context handed to each registered factory at registry-build time. */
+    makeJudgeContext: () => JudgeContext;
+}
+export declare class JudgeStepController {
+    private readonly deps;
+    private registryCache?;
+    constructor(deps: JudgeStepControllerDeps);
+    /**
+     * The registered judge for an agent kind, or undefined when the kind is not a judge. Built
+     * lazily (the factories close over the engine seams) and cached per instance — so, like the
+     * gate registry, a judge registered AFTER the first build is invisible to this instance:
+     * register at startup, before serving.
+     */
+    judgeFor(agentKind: string): JudgeDefinition | undefined;
+    /** Every registered judge, for the workspace-snapshot palette projection. */
+    all(): JudgeDefinition[];
+    /**
+     * The run's "active" judge state: prefer the step the run is currently on, else the latest
+     * step that carries judge state (a pipeline may place more than one judge). Mirrors
+     * `ForkDecisionController.getActive`; null when the run carries none.
+     */
+    getActive(workspaceId: string, executionId: string): Promise<JudgeStepState | null>;
+    /**
+     * The PASS-THROUGH branch: no assessor wired (tests / no model configured) or the judge's own
+     * prerequisite is unwired. Recorded as `skipped` WITH a note — a judge that quietly did nothing
+     * must not read like one that passed — then finished like any other step.
+     */
+    private passThrough;
+    /**
+     * Initialise `step.judge` on first entry. The threshold + bounce budget come from the task's
+     * merge preset ONCE and stay stable across bounce rounds — a preset edited mid-run must not
+     * move the bar the earlier rounds were judged against.
+     */
+    private initState;
+    /**
+     * Evaluate a judge step once: assess, dispose, and act. Shared by the fresh advance and the
+     * re-entry after a bounce (the producer re-ran and the work is ready to be re-judged).
+     */
+    evaluate(workspaceId: string, instance: ExecutionInstance, step: PipelineStep, block: Block, isFinalStep: boolean, judge: JudgeDefinition): Promise<AdvanceResult>;
+    /**
+     * Run the assessment and parse it with the registration's parser. A THROWN assessment (an
+     * unresolved model, a provider outage, an unparseable reply) becomes a score-0 verdict rather
+     * than an exception: the judge's whole job is to gate, so "I could not tell" must land on the
+     * cautious side of the threshold and reach a human, not abort the run with a stack trace or —
+     * worse — let the work through.
+     */
+    private assess;
+    /**
+     * Re-arm the producing step with the verdict's findings as rework feedback and re-run it
+     * through this judge. Uses `rerunProducerThrough` rather than a hand-rolled cursor rewind
+     * because that is what clears the stale container job handles on the intermediate steps (a
+     * re-dispatch would otherwise re-attach to an evicted job).
+     */
+    private bounce;
+    /** Park on a human decision and raise the `judge_review` card that makes it discoverable. */
+    private park;
+    /**
+     * Resolve a parked judge — the SINGLE entry point behind both the SPA controller and the
+     * public API's decisions surface, so the park's CAS/approval-id arbitration and the task's
+     * preset knobs apply identically whichever surface answers first.
+     *
+     *  - `proceed` — advance past the judge despite the verdict (the human overrules the rubric);
+     *  - `bounce`  — spend a rework round on the producing step, even past the preset budget
+     *                (the human is explicitly buying it);
+     *  - `stop`    — fail the run with the verdict.
+     */
+    resolveDecision(workspaceId: string, executionId: string, input: ResolveJudgeInput): Promise<JudgeStepState>;
+    /**
+     * The index of the step a bounce re-arms: the nearest preceding step whose kind the judge
+     * declares it grades, else the immediately preceding step. `-1` when the judge is the first
+     * step — which degrades a `bounce` to a `park` rather than advancing silently.
+     */
+    private bounceTargetIndex;
+    /**
+     * The rubric body in force: a workspace's prompt-library fragment override when one resolves
+     * for {@link JudgeRubric.fragmentId}, else the registration's default. Best-effort — a
+     * library outage must not turn a rubric gate into a hard failure, so it degrades to the
+     * default (which is a real rubric, not an empty one).
+     */
+    private resolveRubric;
+}
+//# sourceMappingURL=JudgeStepController.d.ts.map

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

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

package/dist/modules/execution/JudgeStepController.js

@@ -0,0 +1,395 @@
+import { ConflictError, disposeJudgeVerdict, renderJudgeRework } from '@cat-factory/kernel';
+import { parseJudgeVerdict } from '@cat-factory/contracts';
+export class JudgeStepController {
+    deps;
+    registryCache;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * The registered judge for an agent kind, or undefined when the kind is not a judge. Built
+     * lazily (the factories close over the engine seams) and cached per instance — so, like the
+     * gate registry, a judge registered AFTER the first build is invisible to this instance:
+     * register at startup, before serving.
+     */
+    judgeFor(agentKind) {
+        if (!this.registryCache) {
+            const map = new Map();
+            const ctx = this.deps.makeJudgeContext();
+            for (const { kind, factory } of this.deps.judgeRegistry.factories()) {
+                map.set(kind, factory(ctx));
+            }
+            this.registryCache = map;
+        }
+        return this.registryCache.get(agentKind);
+    }
+    /** Every registered judge, for the workspace-snapshot palette projection. */
+    all() {
+        return this.deps.judgeRegistry.factories().map(({ kind }) => this.judgeFor(kind));
+    }
+    /**
+     * The run's "active" judge state: prefer the step the run is currently on, else the latest
+     * step that carries judge state (a pipeline may place more than one judge). Mirrors
+     * `ForkDecisionController.getActive`; null when the run carries none.
+     */
+    async getActive(workspaceId, executionId) {
+        const instance = await this.deps.executionRepository.get(workspaceId, executionId);
+        if (!instance)
+            return null;
+        const current = instance.steps[instance.currentStep];
+        if (current?.judge)
+            return current.judge;
+        for (let i = instance.steps.length - 1; i >= 0; i--) {
+            const judge = instance.steps[i]?.judge;
+            if (judge)
+                return judge;
+        }
+        return null;
+    }
+    /**
+     * The PASS-THROUGH branch: no assessor wired (tests / no model configured) or the judge's own
+     * prerequisite is unwired. Recorded as `skipped` WITH a note — a judge that quietly did nothing
+     * must not read like one that passed — then finished like any other step.
+     */
+    passThrough(workspaceId, instance, step, isFinalStep, judge, noAssessor) {
+        const note = noAssessor
+            ? `The "${judge.rubric.name}" review was skipped (no assessment model is configured).`
+            : (judge.unwiredOutput ??
+                `The "${judge.rubric.name}" review was skipped (its provider is not configured).`);
+        step.judge = {
+            ...step.judge,
+            status: 'skipped',
+            rubricId: judge.rubric.id,
+            rubricName: judge.rubric.name,
+            rubricOverridden: step.judge?.rubricOverridden ?? false,
+            bounces: step.judge?.bounces ?? 0,
+            maxBounces: step.judge?.maxBounces ?? 0,
+            rounds: step.judge?.rounds ?? [],
+            note,
+        };
+        return this.deps.recordStepResult(workspaceId, instance, step, isFinalStep, { output: note });
+    }
+    /**
+     * Initialise `step.judge` on first entry. The threshold + bounce budget come from the task's
+     * merge preset ONCE and stay stable across bounce rounds — a preset edited mid-run must not
+     * move the bar the earlier rounds were judged against.
+     */
+    async initState(workspaceId, step, block, judge) {
+        if (step.judge) {
+            step.judge = { ...step.judge, status: 'evaluating' };
+            return step.judge;
+        }
+        const preset = await this.deps.resolveRiskPolicy(workspaceId, block);
+        step.judge = {
+            status: 'evaluating',
+            rubricId: judge.rubric.id,
+            rubricName: judge.rubric.name,
+            rubricOverridden: false,
+            threshold: judge.threshold ? judge.threshold(preset) : preset.judgeMinScore,
+            bounces: 0,
+            maxBounces: judge.attemptBudget ? judge.attemptBudget(preset) : preset.judgeMaxBounces,
+            rounds: [],
+        };
+        return step.judge;
+    }
+    /**
+     * Evaluate a judge step once: assess, dispose, and act. Shared by the fresh advance and the
+     * re-entry after a bounce (the producer re-ran and the work is ready to be re-judged).
+     */
+    async evaluate(workspaceId, instance, step, block, isFinalStep, judge) {
+        const assessor = this.deps.judgeAssessor;
+        if (!assessor?.enabled || judge.wired?.() === false) {
+            return this.passThrough(workspaceId, instance, step, isFinalStep, judge, !assessor?.enabled);
+        }
+        // The live state, kept as a local so the rest of the method reads it without re-narrowing
+        // `step.judge` (which stays the persisted source of truth and is re-assigned below).
+        let judgeState = await this.initState(workspaceId, step, block, judge);
+        const { body: rubric, overridden } = await this.resolveRubric(workspaceId, judge);
+        judgeState.rubricOverridden = overridden;
+        await this.deps.stateMachine.emitInstance(workspaceId, instance);
+        const stepIndex = instance.steps.indexOf(step);
+        const { verdict, model } = await this.assess(assessor, {
+            workspaceId,
+            block,
+            step,
+            rubric,
+            rubricName: judge.rubric.name,
+            priorOutputs: priorOutputsFor(instance, stepIndex),
+            previousFindings: judgeState.verdict ?? null,
+        }, judge, instance.initiatedBy ?? null);
+        const producerIndex = this.bounceTargetIndex(instance, stepIndex, judge);
+        const decision = disposeJudgeVerdict({
+            verdict,
+            threshold: judgeState.threshold ?? 0,
+            onFail: judge.onFail,
+            bounces: judgeState.bounces ?? 0,
+            maxBounces: judgeState.maxBounces ?? 0,
+            hasBounceTarget: producerIndex >= 0,
+        });
+        judgeState = {
+            ...judgeState,
+            verdict,
+            model,
+            disposition: decision.disposition,
+            note: decision.note ?? null,
+            rounds: [
+                ...(judgeState.rounds ?? []),
+                {
+                    round: (judgeState.rounds?.length ?? 0) + 1,
+                    at: this.deps.clock.now(),
+                    verdict,
+                    disposition: decision.disposition,
+                    model,
+                },
+            ],
+        };
+        step.judge = judgeState;
+        switch (decision.disposition) {
+            case 'pass':
+                judgeState.status = 'passed';
+                return this.deps.recordStepResult(workspaceId, instance, step, isFinalStep, {
+                    output: renderPassOutput(judge, verdict, judgeState.threshold ?? 0),
+                });
+            case 'fail':
+                judgeState.status = 'failed';
+                await this.deps.stateMachine.casPersist(workspaceId, instance);
+                await this.deps.stateMachine.emitInstance(workspaceId, instance);
+                return {
+                    kind: 'job_failed',
+                    error: `The "${judge.rubric.name}" review failed this work (${verdict.score.toFixed(2)} < ${(judgeState.threshold ?? 0).toFixed(2)}). ${verdict.summary}`.trim(),
+                };
+            case 'bounce':
+                return this.bounce(workspaceId, instance, {
+                    step,
+                    judge,
+                    verdict,
+                    producerIndex,
+                    stepIndex,
+                });
+            default:
+                return this.park(workspaceId, instance, step, block, judge, verdict);
+        }
+    }
+    /**
+     * Run the assessment and parse it with the registration's parser. A THROWN assessment (an
+     * unresolved model, a provider outage, an unparseable reply) becomes a score-0 verdict rather
+     * than an exception: the judge's whole job is to gate, so "I could not tell" must land on the
+     * cautious side of the threshold and reach a human, not abort the run with a stack trace or —
+     * worse — let the work through.
+     */
+    async assess(assessor, subject, judge, initiatedBy) {
+        const parse = judge.parseVerdict ?? parseJudgeVerdict;
+        try {
+            const raw = await this.deps.runInitiatorScope(initiatedBy, () => assessor.assess(subject));
+            return { verdict: parse(raw.verdict), model: raw.model };
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            return {
+                verdict: {
+                    score: 0,
+                    summary: `The "${judge.rubric.name}" assessment could not be completed: ${reason}`,
+                    findings: [
+                        {
+                            title: 'The rubric assessment did not produce a readable verdict',
+                            detail: reason,
+                            severity: 'high',
+                        },
+                    ],
+                },
+                model: null,
+            };
+        }
+    }
+    /**
+     * Re-arm the producing step with the verdict's findings as rework feedback and re-run it
+     * through this judge. Uses `rerunProducerThrough` rather than a hand-rolled cursor rewind
+     * because that is what clears the stale container job handles on the intermediate steps (a
+     * re-dispatch would otherwise re-attach to an evicted job).
+     */
+    async bounce(workspaceId, instance, args) {
+        const { step, judge, verdict, producerIndex, stepIndex, extraFeedback } = args;
+        const judgeState = {
+            ...step.judge,
+            status: 'bouncing',
+            bounces: (step.judge?.bounces ?? 0) + 1,
+        };
+        this.deps.stepGraph.rerunProducerThrough(instance, producerIndex, stepIndex, {
+            previousProposal: instance.steps[producerIndex]?.output ?? '',
+            feedback: renderJudgeRework(verdict, judge.rubric.name, extraFeedback),
+        });
+        // `rerunProducerThrough` resets the judge step too; `judge` survives `resetStepForRerun`
+        // by design, but re-assign explicitly so the incremented bounce count is what persists.
+        step.judge = judgeState;
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+        await this.deps.stateMachine.casPersist(workspaceId, instance);
+        await this.deps.stateMachine.updateBlockProgress(workspaceId, instance, 'in_progress');
+        await this.deps.stateMachine.emitInstance(workspaceId, instance);
+        return { kind: 'continue' };
+    }
+    /** Park on a human decision and raise the `judge_review` card that makes it discoverable. */
+    async park(workspaceId, instance, step, block, judge, verdict) {
+        step.judge = { ...step.judge, status: 'awaiting_decision' };
+        const threshold = step.judge.threshold ?? 0;
+        await this.deps.raiseNotification(workspaceId, {
+            type: 'judge_review',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `"${judge.rubric.name}" review needs a decision for "${block.title}"`,
+            body: `The review scored this work ${verdict.score.toFixed(2)} against a threshold of ` +
+                `${threshold.toFixed(2)}. ${verdict.summary} ` +
+                `Proceed anyway, send it back for rework, or stop the run.`.trim(),
+            payload: {
+                pipelineName: instance.pipelineName,
+                ...(block.pullRequest?.url ? { prUrl: block.pullRequest.url } : {}),
+            },
+        });
+        return this.deps.stateMachine.parkStepOnDecision(workspaceId, instance, step);
+    }
+    /**
+     * Resolve a parked judge — the SINGLE entry point behind both the SPA controller and the
+     * public API's decisions surface, so the park's CAS/approval-id arbitration and the task's
+     * preset knobs apply identically whichever surface answers first.
+     *
+     *  - `proceed` — advance past the judge despite the verdict (the human overrules the rubric);
+     *  - `bounce`  — spend a rework round on the producing step, even past the preset budget
+     *                (the human is explicitly buying it);
+     *  - `stop`    — fail the run with the verdict.
+     */
+    async resolveDecision(workspaceId, executionId, input) {
+        const feedback = input.feedback?.trim() || undefined;
+        let approvalId = '';
+        let stepIndex = -1;
+        let bounceTo = -1;
+        let state;
+        let failure;
+        const instance = await this.deps.stateMachine.mutateInstance(workspaceId, executionId, (inst) => {
+            const index = inst.steps.findIndex((s) => s.state === 'waiting_decision' &&
+                s.approval?.status === 'pending' &&
+                s.judge?.status === 'awaiting_decision');
+            const step = index >= 0 ? inst.steps[index] : undefined;
+            if (!step?.approval || !step.judge) {
+                throw new ConflictError('The run is no longer awaiting a review decision');
+            }
+            const judge = this.judgeFor(step.agentKind);
+            if (!judge) {
+                throw new ConflictError(`No judge is registered for step kind '${step.agentKind}'`);
+            }
+            approvalId = step.approval.id;
+            stepIndex = index;
+            const resolution = {
+                choice: input.choice,
+                at: this.deps.clock.now(),
+                ...(feedback ? { feedback } : {}),
+            };
+            if (input.choice === 'bounce') {
+                bounceTo = this.bounceTargetIndex(inst, index, judge);
+                if (bounceTo < 0) {
+                    throw new ConflictError('There is no preceding step to send this work back to');
+                }
+                // Recorded here so the re-armed run carries the human's intent; the actual rewind
+                // happens on the winning snapshot below (it mutates several steps).
+                step.judge = { ...step.judge, resolution, disposition: 'bounce' };
+                return;
+            }
+            if (input.choice === 'stop') {
+                step.judge = { ...step.judge, status: 'failed', resolution, disposition: 'fail' };
+                failure =
+                    `The "${judge.rubric.name}" review was stopped by a human. ${step.judge.verdict?.summary ?? ''}`.trim();
+                state = step.judge;
+                return;
+            }
+            // `proceed`: the human overrules the rubric — stamp the judge passed and advance the
+            // run past it in the SAME mutation, exactly like an approved gate.
+            step.judge = {
+                ...step.judge,
+                status: 'passed',
+                resolution,
+                disposition: 'pass',
+                note: 'A human chose to proceed despite the verdict.',
+            };
+            step.output = `The "${judge.rubric.name}" review was overruled by a human; the run proceeded.`;
+            state = step.judge;
+            this.deps.stateMachine.advanceRunPastGate(inst, index);
+        });
+        if (input.choice === 'proceed') {
+            await this.deps.stateMachine.settleAdvancedGate(workspaceId, instance, stepIndex);
+            return state;
+        }
+        if (input.choice === 'stop') {
+            await this.deps.stateMachine.clearWaitingNotification(workspaceId, instance);
+            await this.deps.workRunner.signalDecision(workspaceId, instance.id, approvalId, 'rejected');
+            await this.deps.stateMachine.failRun(workspaceId, instance.id, failure, 'agent');
+            return state;
+        }
+        // `bounce`: re-arm the producer with the verdict + the human's extra guidance, then wake
+        // the driver. A human-bought round is NOT charged against the preset budget — they already
+        // decided; charging it would let the next automatic round be silently refused.
+        const step = instance.steps[stepIndex];
+        const judge = this.judgeFor(step.agentKind);
+        const verdict = step.judge?.verdict ?? { score: 0, summary: '', findings: [] };
+        this.deps.stepGraph.rerunProducerThrough(instance, bounceTo, stepIndex, {
+            previousProposal: instance.steps[bounceTo]?.output ?? '',
+            feedback: renderJudgeRework(verdict, judge.rubric.name, feedback),
+        });
+        step.judge = { ...step.judge, status: 'bouncing' };
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+        await this.deps.stateMachine.casPersist(workspaceId, instance);
+        await this.deps.stateMachine.clearWaitingNotification(workspaceId, instance);
+        await this.deps.stateMachine.updateBlockProgress(workspaceId, instance, 'in_progress');
+        await this.deps.stateMachine.emitInstance(workspaceId, instance);
+        await this.deps.workRunner.signalDecision(workspaceId, instance.id, approvalId, 'approved');
+        return step.judge;
+    }
+    /**
+     * The index of the step a bounce re-arms: the nearest preceding step whose kind the judge
+     * declares it grades, else the immediately preceding step. `-1` when the judge is the first
+     * step — which degrades a `bounce` to a `park` rather than advancing silently.
+     */
+    bounceTargetIndex(instance, stepIndex, judge) {
+        const targets = judge.bounceTargets;
+        if (targets?.length) {
+            return this.deps.stepGraph.nearestStepIndexBefore(instance.steps, stepIndex, (s) => targets.includes(s.agentKind));
+        }
+        return stepIndex - 1;
+    }
+    /**
+     * The rubric body in force: a workspace's prompt-library fragment override when one resolves
+     * for {@link JudgeRubric.fragmentId}, else the registration's default. Best-effort — a
+     * library outage must not turn a rubric gate into a hard failure, so it degrades to the
+     * default (which is a real rubric, not an empty one).
+     */
+    async resolveRubric(workspaceId, judge) {
+        const fragmentId = judge.rubric.fragmentId;
+        if (!fragmentId || !this.deps.fragmentResolver)
+            return { body: judge.rubric.body, overridden: false };
+        try {
+            const resolved = await this.deps.fragmentResolver.resolveBodiesForRun(workspaceId, [
+                fragmentId,
+            ]);
+            const body = resolved.find((f) => f.id === fragmentId)?.body?.trim();
+            if (body)
+                return { body, overridden: true };
+        }
+        catch {
+            // Fall through to the default rubric.
+        }
+        return { body: judge.rubric.body, overridden: false };
+    }
+}
+/** The step outputs the judge reviews: every preceding step that produced one, oldest first. */
+function priorOutputsFor(instance, stepIndex) {
+    return instance.steps
+        .slice(0, Math.max(stepIndex, 0))
+        .filter((s) => !!s.output?.trim())
+        .map((s) => ({ agentKind: s.agentKind, output: s.output }));
+}
+/** The step output a PASSING judge records (what it scored, and what it still noted). */
+function renderPassOutput(judge, verdict, threshold) {
+    const nits = verdict.findings?.length ?? 0;
+    const suffix = nits > 0 ? ` ${nits} non-blocking finding(s) recorded.` : '';
+    return `The "${judge.rubric.name}" review passed (${verdict.score.toFixed(2)} ≥ ${threshold.toFixed(2)}).${suffix}`;
+}
+//# sourceMappingURL=JudgeStepController.js.map