@cat-factory/orchestration 0.6.0

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

@@ -0,0 +1,97 @@
+import type { Block, ExecutionInstance, GateStepState, MergeThresholdPreset, PipelineStep } from '@cat-factory/kernel';
+/** The outcome of a single gate precheck against its provider. */
+export interface GateProbe {
+    /**
+     *  - `pass`    — the precheck is satisfied; the step finishes and the run advances
+     *                (the "skip the agent" path — nothing was spun up).
+     *  - `pending` — the provider is still computing; keep polling.
+     *  - `fail`    — the precheck failed; escalate to the helper agent (or give up once
+     *                the attempt budget is spent).
+     */
+    status: 'pass' | 'pending' | 'fail';
+    /** The PR head commit the precheck ran against, or null when there is no open PR. */
+    headSha: string | null;
+    /** Step output recorded on `pass` (a short human-readable reason). */
+    passOutput?: string;
+    /** A summary of what failed on `fail` — fed to the helper agent and the give-up error. */
+    failureSummary?: string;
+    /**
+     * Structured failing checks behind {@link failureSummary} (the CI gate populates
+     * this from the red check runs; the conflicts gate leaves it undefined). Persisted
+     * onto `step.gate` so the run-detail UI can list each failing check.
+     */
+    failingChecks?: {
+        name: string;
+        conclusion: string | null;
+    }[];
+}
+/** Inputs to a gate's exhaustion handler (budget spent / no executor to escalate to). */
+export interface GateExhaustedArgs {
+    workspaceId: string;
+    instance: ExecutionInstance;
+    block: Block;
+    step: PipelineStep;
+    summary?: string;
+}
+/**
+ * The per-gate differentiators the engine's generic gate machine needs. Everything
+ * shared (the state machine, persistence, dispatch, budget) lives in ExecutionService.
+ */
+export interface GateDefinition {
+    /** Matches the step's `agentKind` (e.g. `ci`, `conflicts`). */
+    kind: string;
+    /** The container agent kind dispatched on a failed precheck (e.g. `ci-fixer`). */
+    helperKind: string;
+    /** Whether the gate's provider is wired. When false the gate is a pass-through. */
+    wired(): boolean;
+    /** Step output recorded when the gate passes through (no provider configured). */
+    unwiredOutput: string;
+    /**
+     * What to do when the durable driver's poll budget (ciMaxPolls × ciPollInterval) is
+     * spent while the gate is still `pending` — distinct from the attempt budget (helper
+     * dispatches) handled by {@link onExhausted}:
+     *   - `fail` (default) — the precheck never settled, which is a failure for the CI /
+     *     conflicts gates (CI never went green / the PR never became mergeable).
+     *   - `pass` — for a time-windowed watch gate (post-release-health), running out of
+     *     polls just means the watch window outlasted the budget with NO regression seen,
+     *     which is a healthy pass — not a timeout failure.
+     * Resolved by {@link ExecutionService.resolveGatePollExhaustion}.
+     */
+    pollExhaustion?: 'pass' | 'fail';
+    /**
+     * Run the precheck against the provider and classify it. Receives the live gate
+     * state so a time-windowed gate (post-release-health) can read its `watchSince`.
+     */
+    probe(workspaceId: string, blockId: string, gateState: GateStepState): Promise<GateProbe>;
+    /**
+     * Optional: the attempt budget for this gate, resolved from the task's merge preset.
+     * Defaults to `ciMaxAttempts` when omitted (the CI/conflicts gates use that).
+     */
+    attemptBudget?(preset: Pick<MergeThresholdPreset, 'ciMaxAttempts' | 'releaseMaxAttempts'>): number;
+    /**
+     * Optional extra context handed to the helper agent on escalation (the CI gate
+     * passes the failing-check summary; the conflicts gate passes nothing).
+     */
+    helperPriorOutput?(summary: string): {
+        agentKind: string;
+        output: string;
+    } | undefined;
+    /**
+     * Optional async builder for richer helper context (gathered at dispatch time), used
+     * when a gate's helper needs more than the precheck summary — e.g. the on-call agent
+     * gets the full Datadog evidence bundle. Returns prior-output entries appended after
+     * the base context's. Takes precedence over {@link helperPriorOutput} when present.
+     */
+    gatherHelperPriorOutputs?(workspaceId: string, blockId: string, gateState: GateStepState): Promise<{
+        agentKind: string;
+        output: string;
+    }[]>;
+    /**
+     * Called when the attempt budget is spent (or there is no async executor to escalate
+     * to). May raise a notification; returns the message used to fail the run.
+     */
+    onExhausted(args: GateExhaustedArgs): Promise<{
+        error: string;
+    }>;
+}
+//# sourceMappingURL=gates.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gates.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/gates.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EACL,iBAAiB,EACjB,aAAa,EACb,oBAAoB,EACpB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAa5B,kEAAkE;AAClE,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;IACnC,qFAAqF;IACrF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,0FAA0F;IAC1F,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,EAAE,CAAA;CAC9D;AAED,yFAAyF;AACzF,MAAM,WAAW,iBAAiB;IAChC,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,KAAK,EAAE,KAAK,CAAA;IACZ,IAAI,EAAE,YAAY,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAA;IACZ,kFAAkF;IAClF,UAAU,EAAE,MAAM,CAAA;IAClB,mFAAmF;IACnF,KAAK,IAAI,OAAO,CAAA;IAChB,kFAAkF;IAClF,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAChC;;;OAGG;IACH,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,aAAa,GAAG,OAAO,CAAC,SAAS,CAAC,CAAA;IACzF;;;OAGG;IACH,aAAa,CAAC,CAAC,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,eAAe,GAAG,oBAAoB,CAAC,GAAG,MAAM,CAAA;IAClG;;;OAGG;IACH,iBAAiB,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAA;IACtF;;;;;OAKG;IACH,wBAAwB,CAAC,CACvB,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,aAAa,GACvB,OAAO,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC,CAAA;IACnD;;;OAGG;IACH,WAAW,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjE"}

package/dist/modules/execution/gates.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gates.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"gates.js","sourceRoot":"","sources":["../../../src/modules/execution/gates.ts"],"names":[],"mappings":""}

package/dist/modules/execution/individualVendors.logic.d.ts

@@ -0,0 +1,22 @@
+import { type SubscriptionVendor } from '@cat-factory/kernel';
+/** Resolve the workspace per-kind default model id (the model-defaults feature). */
+export type WorkspaceModelDefaultResolver = (kind: string) => Promise<string | undefined>;
+/** Whether the run's user has their OWN personal subscription for an individual vendor. */
+export type HasPersonalSubscription = (vendor: SubscriptionVendor) => boolean;
+/**
+ * The individual-usage subscription vendors (Claude / Codex / GLM-for-a-subscriber) a run
+ * will ACTUALLY lease a personal credential for, so the caller can gate it on the
+ * initiator's personal subscription(s) up-front. Mirrors dispatch on TWO axes:
+ *
+ *  - Model precedence ({@link resolveStepModelRef}): a RESOLVABLE block pin applies to
+ *    every step, so it alone decides the set; only an unpinned run (or a stale/unknown
+ *    id) falls to the workspace per-kind defaults. Env-routing defaults (dispatch's last
+ *    fallback) are operator-level and not gated.
+ *  - Personal-credential need ({@link personalCredentialVendorForModelId}, mirroring
+ *    `ContainerAgentExecutor.resolveEffectiveRef`): a credential is leased for a
+ *    subscription-only individual model (Claude / Codex) always, and for a DUAL-MODE
+ *    individual model (GLM) only when THIS user has their own subscription for it (else
+ *    it runs on the Cloudflare base, ungated). `hasPersonalSubscription` reports that.
+ */
+export declare function resolveIndividualVendors(blockModelId: string | undefined, agentKinds: string[], resolveWorkspaceModelDefault: WorkspaceModelDefaultResolver | undefined, hasPersonalSubscription: HasPersonalSubscription): Promise<SubscriptionVendor[]>;
+//# sourceMappingURL=individualVendors.logic.d.ts.map

package/dist/modules/execution/individualVendors.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"individualVendors.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/individualVendors.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,qBAAqB,CAAA;AAE5B,oFAAoF;AACpF,MAAM,MAAM,6BAA6B,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAEzF,2FAA2F;AAC3F,MAAM,MAAM,uBAAuB,GAAG,CAAC,MAAM,EAAE,kBAAkB,KAAK,OAAO,CAAA;AAE7E;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,wBAAwB,CAC5C,YAAY,EAAE,MAAM,GAAG,SAAS,EAChC,UAAU,EAAE,MAAM,EAAE,EACpB,4BAA4B,EAAE,6BAA6B,GAAG,SAAS,EACvE,uBAAuB,EAAE,uBAAuB,GAC/C,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAa/B"}

package/dist/modules/execution/individualVendors.logic.js

@@ -0,0 +1,33 @@
+import { getSelectableModel, personalCredentialVendorForModelId, } from '@cat-factory/kernel';
+/**
+ * The individual-usage subscription vendors (Claude / Codex / GLM-for-a-subscriber) a run
+ * will ACTUALLY lease a personal credential for, so the caller can gate it on the
+ * initiator's personal subscription(s) up-front. Mirrors dispatch on TWO axes:
+ *
+ *  - Model precedence ({@link resolveStepModelRef}): a RESOLVABLE block pin applies to
+ *    every step, so it alone decides the set; only an unpinned run (or a stale/unknown
+ *    id) falls to the workspace per-kind defaults. Env-routing defaults (dispatch's last
+ *    fallback) are operator-level and not gated.
+ *  - Personal-credential need ({@link personalCredentialVendorForModelId}, mirroring
+ *    `ContainerAgentExecutor.resolveEffectiveRef`): a credential is leased for a
+ *    subscription-only individual model (Claude / Codex) always, and for a DUAL-MODE
+ *    individual model (GLM) only when THIS user has their own subscription for it (else
+ *    it runs on the Cloudflare base, ungated). `hasPersonalSubscription` reports that.
+ */
+export async function resolveIndividualVendors(blockModelId, agentKinds, resolveWorkspaceModelDefault, hasPersonalSubscription) {
+    if (blockModelId && getSelectableModel(blockModelId)) {
+        const pinned = personalCredentialVendorForModelId(blockModelId, hasPersonalSubscription);
+        return pinned ? [pinned] : [];
+    }
+    if (!resolveWorkspaceModelDefault || agentKinds.length === 0)
+        return [];
+    const vendors = new Set();
+    for (const kind of agentKinds) {
+        const defaultId = await resolveWorkspaceModelDefault(kind);
+        const vendor = personalCredentialVendorForModelId(defaultId, hasPersonalSubscription);
+        if (vendor)
+            vendors.add(vendor);
+    }
+    return [...vendors];
+}
+//# sourceMappingURL=individualVendors.logic.js.map

package/dist/modules/execution/individualVendors.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"individualVendors.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/individualVendors.logic.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,kCAAkC,GAEnC,MAAM,qBAAqB,CAAA;AAQ5B;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,YAAgC,EAChC,UAAoB,EACpB,4BAAuE,EACvE,uBAAgD;IAEhD,IAAI,YAAY,IAAI,kBAAkB,CAAC,YAAY,CAAC,EAAE,CAAC;QACrD,MAAM,MAAM,GAAG,kCAAkC,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAA;QACxF,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;IAC/B,CAAC;IACD,IAAI,CAAC,4BAA4B,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACvE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;IAC7C,KAAK,MAAM,IAAI,IAAI,UAAU,EAAE,CAAC;QAC9B,MAAM,SAAS,GAAG,MAAM,4BAA4B,CAAC,IAAI,CAAC,CAAA;QAC1D,MAAM,MAAM,GAAG,kCAAkC,CAAC,SAAS,EAAE,uBAAuB,CAAC,CAAA;QACrF,IAAI,MAAM;YAAE,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IACD,OAAO,CAAC,GAAG,OAAO,CAAC,CAAA;AACrB,CAAC"}

package/dist/modules/execution/job.logic.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Maximum number of times a step's *crash* eviction (OOM / a genuine crash) is
+ * recovered automatically by re-dispatching a fresh container for the same step.
+ * Set to 1: one blip is recovered silently; a second crash of the same step is
+ * treated as deterministic and fails the run (`evicted`). Evictions a runtime flags
+ * as transient infra churn get their own, larger budget — see
+ * {@link MAX_TRANSIENT_EVICTION_RECOVERIES}.
+ */
+export declare const MAX_EVICTION_RECOVERIES = 1;
+/**
+ * Recovery budget for evictions a runtime flags as *transient infrastructure churn*
+ * (see {@link isTransientEviction}) rather than a crash. Larger than
+ * {@link MAX_EVICTION_RECOVERIES} because such churn can recur several times in a
+ * short window (e.g. a deploy that drains the sandbox repeatedly). Each recovery
+ * re-dispatches a fresh container, naturally spaced by the job poll interval, so a
+ * bounded handful rides out the window instead of deterministically failing a
+ * healthy run. The engine stays runtime-neutral: which infra events count as
+ * transient is the facade's call — it opts in by tagging the eviction with
+ * {@link TRANSIENT_EVICTION_MARKER} (Cloudflare maps a new-version rollout / exit
+ * 143 to it; another runtime might map a node drain or a placement move).
+ */
+export declare const MAX_TRANSIENT_EVICTION_RECOVERIES = 5;
+/**
+ * Neutral marker a runtime facade appends to an eviction error to declare it
+ * transient infrastructure churn (recover leniently), not a crash. Kept generic on
+ * purpose: the engine knows only "transient vs crash"; the facade owns the mapping
+ * from its own signal (a Cloudflare rollout, a node drain, …) to this marker. The
+ * tagged string still contains "evicted or crashed" so {@link isContainerEvictionError}
+ * also matches and the shared recovery machinery engages.
+ */
+export declare const TRANSIENT_EVICTION_MARKER = "transient infrastructure eviction";
+/**
+ * Whether a failed job poll is a *container eviction/crash* (the per-run container
+ * vanished and its in-memory job registry is gone) rather than a genuine agent
+ * failure. The Cloudflare transport maps a 404 job poll to a failed view whose
+ * message ends `(container evicted or crashed)`; the worker bootstrap flow
+ * classifies the identical string. Matching it here lets the execution engine
+ * recover a transient eviction by spinning a fresh container instead of failing
+ * the whole run on the first blip. Covers transient-tagged evictions too (their
+ * message also contains this phrase) — {@link isTransientEviction} sub-classifies them.
+ */
+export declare function isContainerEvictionError(error: string | undefined): boolean;
+/**
+ * Whether a container eviction was flagged by the runtime facade as *transient
+ * infrastructure churn* (the facade tagged it with {@link TRANSIENT_EVICTION_MARKER})
+ * rather than a crash/OOM. Transient evictions recover on the larger
+ * {@link MAX_TRANSIENT_EVICTION_RECOVERIES} budget. This is intentionally agnostic to
+ * what the underlying event was: the facade decides (Cloudflare, for instance, maps a
+ * new-version rollout to it after asking the container Durable Object).
+ */
+export declare function isTransientEviction(error: string | undefined): boolean;
+//# sourceMappingURL=job.logic.d.ts.map

package/dist/modules/execution/job.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/job.logic.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,IAAI,CAAA;AAExC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAA;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,sCAAsC,CAAA;AAE5E;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAE3E;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAEtE"}

package/dist/modules/execution/job.logic.js

@@ -0,0 +1,56 @@
+/**
+ * Maximum number of times a step's *crash* eviction (OOM / a genuine crash) is
+ * recovered automatically by re-dispatching a fresh container for the same step.
+ * Set to 1: one blip is recovered silently; a second crash of the same step is
+ * treated as deterministic and fails the run (`evicted`). Evictions a runtime flags
+ * as transient infra churn get their own, larger budget — see
+ * {@link MAX_TRANSIENT_EVICTION_RECOVERIES}.
+ */
+export const MAX_EVICTION_RECOVERIES = 1;
+/**
+ * Recovery budget for evictions a runtime flags as *transient infrastructure churn*
+ * (see {@link isTransientEviction}) rather than a crash. Larger than
+ * {@link MAX_EVICTION_RECOVERIES} because such churn can recur several times in a
+ * short window (e.g. a deploy that drains the sandbox repeatedly). Each recovery
+ * re-dispatches a fresh container, naturally spaced by the job poll interval, so a
+ * bounded handful rides out the window instead of deterministically failing a
+ * healthy run. The engine stays runtime-neutral: which infra events count as
+ * transient is the facade's call — it opts in by tagging the eviction with
+ * {@link TRANSIENT_EVICTION_MARKER} (Cloudflare maps a new-version rollout / exit
+ * 143 to it; another runtime might map a node drain or a placement move).
+ */
+export const MAX_TRANSIENT_EVICTION_RECOVERIES = 5;
+/**
+ * Neutral marker a runtime facade appends to an eviction error to declare it
+ * transient infrastructure churn (recover leniently), not a crash. Kept generic on
+ * purpose: the engine knows only "transient vs crash"; the facade owns the mapping
+ * from its own signal (a Cloudflare rollout, a node drain, …) to this marker. The
+ * tagged string still contains "evicted or crashed" so {@link isContainerEvictionError}
+ * also matches and the shared recovery machinery engages.
+ */
+export const TRANSIENT_EVICTION_MARKER = 'transient infrastructure eviction';
+/**
+ * Whether a failed job poll is a *container eviction/crash* (the per-run container
+ * vanished and its in-memory job registry is gone) rather than a genuine agent
+ * failure. The Cloudflare transport maps a 404 job poll to a failed view whose
+ * message ends `(container evicted or crashed)`; the worker bootstrap flow
+ * classifies the identical string. Matching it here lets the execution engine
+ * recover a transient eviction by spinning a fresh container instead of failing
+ * the whole run on the first blip. Covers transient-tagged evictions too (their
+ * message also contains this phrase) — {@link isTransientEviction} sub-classifies them.
+ */
+export function isContainerEvictionError(error) {
+    return error !== undefined && /evicted or crashed/i.test(error);
+}
+/**
+ * Whether a container eviction was flagged by the runtime facade as *transient
+ * infrastructure churn* (the facade tagged it with {@link TRANSIENT_EVICTION_MARKER})
+ * rather than a crash/OOM. Transient evictions recover on the larger
+ * {@link MAX_TRANSIENT_EVICTION_RECOVERIES} budget. This is intentionally agnostic to
+ * what the underlying event was: the facade decides (Cloudflare, for instance, maps a
+ * new-version rollout to it after asking the container Durable Object).
+ */
+export function isTransientEviction(error) {
+    return error !== undefined && error.includes(TRANSIENT_EVICTION_MARKER);
+}
+//# sourceMappingURL=job.logic.js.map

package/dist/modules/execution/job.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"job.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/job.logic.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAA;AAExC;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,CAAA;AAElD;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,mCAAmC,CAAA;AAE5E;;;;;;;;;GASG;AACH,MAAM,UAAU,wBAAwB,CAAC,KAAyB;IAChE,OAAO,KAAK,KAAK,SAAS,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACjE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAyB;IAC3D,OAAO,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,yBAAyB,CAAC,CAAA;AACzE,CAAC"}

package/dist/modules/execution/release.logic.d.ts

@@ -0,0 +1,43 @@
+import type { ReleaseHealthReport, ReleaseSignal } from '@cat-factory/kernel';
+/**
+ * The agent kind of the special post-release-health gate step. Like `ci`/`conflicts`
+ * it is NOT a container/inline LLM agent: it polls a `ReleaseHealthProvider` (Datadog
+ * monitors/SLOs) over a monitoring window after deploy and only escalates to the
+ * `on-call` agent on a regression. Passes through when no provider/config is wired.
+ */
+export declare const POST_RELEASE_HEALTH_AGENT_KIND = "post-release-health";
+/**
+ * The agent kind of the `on-call` container agent dispatched on a release regression.
+ * It clones the released PR head, reasons over the evidence bundle (alerting
+ * monitors/SLOs + recent error logs) against the diff, and returns a JSON assessment
+ * (culprit confidence + recommendation). It makes NO commits and reverts nothing —
+ * the engine raises a `release_regression` notification for a human to decide.
+ */
+export declare const ON_CALL_AGENT_KIND = "on-call";
+/** The gate verdict for one post-release-health probe. */
+export type ReleaseGateVerdict = 'pass' | 'pending' | 'fail';
+/**
+ * Decide the gate verdict from the provider's signal verdict + the monitoring-window
+ * timing:
+ *  - `regressed`                       → `fail` (escalate to the on-call agent).
+ *  - anything else & window not elapsed → `pending` (keep watching the rest of the window).
+ *  - anything else & window elapsed     → `pass` (no regression observed in the window).
+ *
+ * The non-regressed states (`healthy` AND `pending`/`no_data`) are treated the same way:
+ * keep watching until the window elapses, then pass. This is deliberate — a `pending`
+ * verdict means "no regression detected yet" (e.g. a quiet or `no_data` monitor right
+ * after deploy), NOT "broken". Blocking advancement on it forever (the old behaviour)
+ * meant a permanently-`no_data` monitor burned the whole poll budget and then failed an
+ * otherwise-healthy release as a false `timeout`. The window is the grace period; once it
+ * elapses with nothing alerting, the release ships.
+ *
+ * `warn` states do not regress the gate — only `alert`/SLO-breach (which the provider
+ * maps to `regressed`) do — so a warning threshold doesn't pause the pipeline.
+ */
+export declare function classifyReleaseHealth(args: {
+    report: ReleaseHealthReport;
+    windowElapsed: boolean;
+}): ReleaseGateVerdict;
+/** A short, human-readable summary of the regressed signals, for the notification + on-call. */
+export declare function describeRegressedSignals(signals: ReleaseSignal[]): string;
+//# sourceMappingURL=release.logic.d.ts.map

package/dist/modules/execution/release.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/release.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAE7E;;;;;GAKG;AACH,eAAO,MAAM,8BAA8B,wBAAwB,CAAA;AAEnE;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAE3C,0DAA0D;AAC1D,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAA;AAE5D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,mBAAmB,CAAA;IAC3B,aAAa,EAAE,OAAO,CAAA;CACvB,GAAG,kBAAkB,CAGrB;AAED,gGAAgG;AAChG,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAOzE"}

package/dist/modules/execution/release.logic.js

@@ -0,0 +1,49 @@
+/**
+ * The agent kind of the special post-release-health gate step. Like `ci`/`conflicts`
+ * it is NOT a container/inline LLM agent: it polls a `ReleaseHealthProvider` (Datadog
+ * monitors/SLOs) over a monitoring window after deploy and only escalates to the
+ * `on-call` agent on a regression. Passes through when no provider/config is wired.
+ */
+export const POST_RELEASE_HEALTH_AGENT_KIND = 'post-release-health';
+/**
+ * The agent kind of the `on-call` container agent dispatched on a release regression.
+ * It clones the released PR head, reasons over the evidence bundle (alerting
+ * monitors/SLOs + recent error logs) against the diff, and returns a JSON assessment
+ * (culprit confidence + recommendation). It makes NO commits and reverts nothing —
+ * the engine raises a `release_regression` notification for a human to decide.
+ */
+export const ON_CALL_AGENT_KIND = 'on-call';
+/**
+ * Decide the gate verdict from the provider's signal verdict + the monitoring-window
+ * timing:
+ *  - `regressed`                       → `fail` (escalate to the on-call agent).
+ *  - anything else & window not elapsed → `pending` (keep watching the rest of the window).
+ *  - anything else & window elapsed     → `pass` (no regression observed in the window).
+ *
+ * The non-regressed states (`healthy` AND `pending`/`no_data`) are treated the same way:
+ * keep watching until the window elapses, then pass. This is deliberate — a `pending`
+ * verdict means "no regression detected yet" (e.g. a quiet or `no_data` monitor right
+ * after deploy), NOT "broken". Blocking advancement on it forever (the old behaviour)
+ * meant a permanently-`no_data` monitor burned the whole poll budget and then failed an
+ * otherwise-healthy release as a false `timeout`. The window is the grace period; once it
+ * elapses with nothing alerting, the release ships.
+ *
+ * `warn` states do not regress the gate — only `alert`/SLO-breach (which the provider
+ * maps to `regressed`) do — so a warning threshold doesn't pause the pipeline.
+ */
+export function classifyReleaseHealth(args) {
+    if (args.report.status === 'regressed')
+        return 'fail';
+    return args.windowElapsed ? 'pass' : 'pending';
+}
+/** A short, human-readable summary of the regressed signals, for the notification + on-call. */
+export function describeRegressedSignals(signals) {
+    const bad = signals.filter((s) => s.state === 'alert');
+    if (bad.length === 0)
+        return 'A monitored release signal regressed.';
+    const names = bad
+        .map((s) => `${s.name} (${s.state}${s.detail ? `: ${s.detail}` : ''})`)
+        .join(', ');
+    return `Regressed signals: ${names}`;
+}
+//# sourceMappingURL=release.logic.js.map

package/dist/modules/execution/release.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"release.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/release.logic.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,qBAAqB,CAAA;AAEnE;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAK3C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAGrC;IACC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,MAAM,CAAA;IACrD,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;AAChD,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,wBAAwB,CAAC,OAAwB;IAC/D,MAAM,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,OAAO,CAAC,CAAA;IACtD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,uCAAuC,CAAA;IACpE,MAAM,KAAK,GAAG,GAAG;SACd,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;SACtE,IAAI,CAAC,IAAI,CAAC,CAAA;IACb,OAAO,sBAAsB,KAAK,EAAE,CAAA;AACtC,CAAC"}

package/dist/modules/execution/retry.logic.d.ts

@@ -0,0 +1,40 @@
+import type { PipelineStep } from '@cat-factory/kernel';
+/**
+ * Plan how a failed run resumes on retry: keep the steps that already completed
+ * and re-run from the one that actually failed, rather than restarting the whole
+ * pipeline from step 0. For `pl_full` (`requirements → spec-writer → architect →
+ * researcher → coder → …`) a coder failure otherwise re-runs the human-gated steps
+ * before it; resuming skips straight back to `coder`.
+ *
+ * Pure + deterministic so it can be unit-tested without the service's ports. The
+ * caller mints the new instance id and re-drives the durable runner.
+ */
+export declare function planResumedSteps(prev: {
+    steps: PipelineStep[];
+    currentStep: number;
+}): {
+    steps: PipelineStep[];
+    currentStep: number;
+};
+/**
+ * Plan a user-driven "restart from this step": re-run from the explicitly chosen
+ * `fromIndex` regardless of how far the run had progressed (even a fully `done`
+ * run), keeping every step before it intact and resetting that step + all later
+ * ones to a clean, re-runnable state. Unlike {@link planResumedSteps} the target is
+ * the human's pick, not the first failure — so it can rewind past already-completed
+ * steps. The preserved earlier steps keep their `output`, so the engine still hands
+ * the restarted step its predecessors' work as `priorOutputs` (a useful handoff); a
+ * block's incorporated requirements are NOT touched here — they live on the
+ * requirement-review record, so a restarted spec-writer/coder still reads them (and
+ * restarting AT the requirements-review step itself re-runs the reviewer, which
+ * mints a fresh iteration-1 review).
+ *
+ * Pure + deterministic so it can be unit-tested without the service's ports.
+ */
+export declare function planRestartFromStep(prev: {
+    steps: PipelineStep[];
+}, fromIndex: number): {
+    steps: PipelineStep[];
+    currentStep: number;
+};
+//# sourceMappingURL=retry.logic.d.ts.map

package/dist/modules/execution/retry.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/retry.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEvD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG;IACtF,KAAK,EAAE,YAAY,EAAE,CAAA;IACrB,WAAW,EAAE,MAAM,CAAA;CACpB,CASA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE;IAAE,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,EAC/B,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,YAAY,EAAE,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAShD"}

package/dist/modules/execution/retry.logic.js

@@ -0,0 +1,83 @@
+/**
+ * Plan how a failed run resumes on retry: keep the steps that already completed
+ * and re-run from the one that actually failed, rather than restarting the whole
+ * pipeline from step 0. For `pl_full` (`requirements → spec-writer → architect →
+ * researcher → coder → …`) a coder failure otherwise re-runs the human-gated steps
+ * before it; resuming skips straight back to `coder`.
+ *
+ * Pure + deterministic so it can be unit-tested without the service's ports. The
+ * caller mints the new instance id and re-drives the durable runner.
+ */
+export function planResumedSteps(prev) {
+    // Resume at the first step that did not complete. A failed run normally parked
+    // on `currentStep`, but deriving it from the `done` states is robust to a stale
+    // index and means the steps before it are exactly the ones we preserve.
+    const firstUnfinished = prev.steps.findIndex((s) => s.state !== 'done');
+    // All steps done (shouldn't happen for a failed run): nothing to resume — re-run
+    // the last step so the retry still does something rather than no-op.
+    const resumeIndex = firstUnfinished === -1 ? Math.max(prev.steps.length - 1, 0) : firstUnfinished;
+    return planFromStep(prev.steps, resumeIndex);
+}
+/**
+ * Plan a user-driven "restart from this step": re-run from the explicitly chosen
+ * `fromIndex` regardless of how far the run had progressed (even a fully `done`
+ * run), keeping every step before it intact and resetting that step + all later
+ * ones to a clean, re-runnable state. Unlike {@link planResumedSteps} the target is
+ * the human's pick, not the first failure — so it can rewind past already-completed
+ * steps. The preserved earlier steps keep their `output`, so the engine still hands
+ * the restarted step its predecessors' work as `priorOutputs` (a useful handoff); a
+ * block's incorporated requirements are NOT touched here — they live on the
+ * requirement-review record, so a restarted spec-writer/coder still reads them (and
+ * restarting AT the requirements-review step itself re-runs the reviewer, which
+ * mints a fresh iteration-1 review).
+ *
+ * Pure + deterministic so it can be unit-tested without the service's ports.
+ */
+export function planRestartFromStep(prev, fromIndex) {
+    // Clamp into range so an out-of-bounds index can't strand the run with a
+    // `currentStep` past the last step (the service validates first, but the pure fn
+    // stays total).
+    const resumeIndex = Math.min(Math.max(Math.trunc(fromIndex), 0), Math.max(prev.steps.length - 1, 0));
+    return planFromStep(prev.steps, resumeIndex);
+}
+/**
+ * Shared core of {@link planResumedSteps} / {@link planRestartFromStep}: keep the
+ * steps before `resumeIndex` exactly as-is (their output/approval/timing are the
+ * preserved handoff context) and reset that step + everything after it.
+ */
+function planFromStep(prevSteps, resumeIndex) {
+    const steps = prevSteps.map((step, i) => {
+        if (i < resumeIndex)
+            return step; // completed: preserve output/approval/timing as-is
+        return resetStep(step, i === resumeIndex ? 'working' : 'pending');
+    });
+    return { steps, currentStep: resumeIndex };
+}
+/**
+ * Reset a step to a clean, re-runnable state, dropping every transient field a
+ * prior (partial) attempt may have left behind so the fresh run starts from
+ * scratch: no in-flight job handle, no stale gate/subtask state, no prior output,
+ * fresh timing (`startStep` re-stamps `startedAt`). The structural fields the
+ * pipeline defined — `agentKind` and `requiresApproval` — are preserved so the
+ * approval gate still fires after the re-run.
+ */
+function resetStep(step, state) {
+    return {
+        agentKind: step.agentKind,
+        state,
+        progress: 0,
+        gate: null,
+        subtasks: undefined,
+        decision: null,
+        requiresApproval: step.requiresApproval,
+        approval: null,
+        output: undefined,
+        model: undefined,
+        selectedFragmentIds: undefined,
+        jobId: undefined,
+        startedAt: undefined,
+        finishedAt: undefined,
+        pausedAt: undefined,
+    };
+}
+//# sourceMappingURL=retry.logic.js.map

package/dist/modules/execution/retry.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/retry.logic.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAoD;IAInF,+EAA+E;IAC/E,gFAAgF;IAChF,wEAAwE;IACxE,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,MAAM,CAAC,CAAA;IACvE,iFAAiF;IACjF,qEAAqE;IACrE,MAAM,WAAW,GAAG,eAAe,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAA;IACjG,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;AAC9C,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA+B,EAC/B,SAAiB;IAEjB,yEAAyE;IACzE,iFAAiF;IACjF,gBAAgB;IAChB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAC1B,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAClC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,CAAC,CACnC,CAAA;IACD,OAAO,YAAY,CAAC,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAA;AAC9C,CAAC;AAED;;;;GAIG;AACH,SAAS,YAAY,CACnB,SAAyB,EACzB,WAAmB;IAEnB,MAAM,KAAK,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACtC,IAAI,CAAC,GAAG,WAAW;YAAE,OAAO,IAAI,CAAA,CAAC,mDAAmD;QACpF,OAAO,SAAS,CAAC,IAAI,EAAE,CAAC,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;IACF,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,CAAA;AAC5C,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,SAAS,CAAC,IAAkB,EAAE,KAA4B;IACjE,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK;QACL,QAAQ,EAAE,CAAC;QACX,IAAI,EAAE,IAAI;QACV,QAAQ,EAAE,SAAS;QACnB,QAAQ,EAAE,IAAI;QACd,gBAAgB,EAAE,IAAI,CAAC,gBAAgB;QACvC,QAAQ,EAAE,IAAI;QACd,MAAM,EAAE,SAAS;QACjB,KAAK,EAAE,SAAS;QAChB,mBAAmB,EAAE,SAAS;QAC9B,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,SAAS;QACpB,UAAU,EAAE,SAAS;QACrB,QAAQ,EAAE,SAAS;KACpB,CAAA;AACH,CAAC"}

package/dist/modules/execution/stepGating.logic.d.ts

@@ -0,0 +1,15 @@
+import type { StepGating, TaskEstimate } from '@cat-factory/kernel';
+/**
+ * Decide whether a gated pipeline step should run, given the task estimate and the step's
+ * gating config. Mirrors the consensus-gating decision (OR across axes) but yields a plain
+ * run/skip:
+ *
+ *  - No gating / gating disabled → run (the step is unconditional).
+ *  - Gating enabled, estimate present → run iff ANY supplied axis is met or exceeded
+ *    (risk ≥ minRisk OR impact ≥ minImpact OR complexity ≥ minComplexity). A gating block
+ *    with no thresholds set never triggers on score → skip.
+ *  - Gating enabled, estimate absent → `gating.onMissingEstimate` (default `run`, fail-safe
+ *    to thoroughness).
+ */
+export declare function shouldRunGatedStep(estimate: TaskEstimate | null | undefined, gating: StepGating | null | undefined): boolean;
+//# sourceMappingURL=stepGating.logic.d.ts.map

package/dist/modules/execution/stepGating.logic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepGating.logic.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/stepGating.logic.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAEnE;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACzC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GACpC,OAAO,CAYT"}

package/dist/modules/execution/stepGating.logic.js

@@ -0,0 +1,29 @@
+/**
+ * Decide whether a gated pipeline step should run, given the task estimate and the step's
+ * gating config. Mirrors the consensus-gating decision (OR across axes) but yields a plain
+ * run/skip:
+ *
+ *  - No gating / gating disabled → run (the step is unconditional).
+ *  - Gating enabled, estimate present → run iff ANY supplied axis is met or exceeded
+ *    (risk ≥ minRisk OR impact ≥ minImpact OR complexity ≥ minComplexity). A gating block
+ *    with no thresholds set never triggers on score → skip.
+ *  - Gating enabled, estimate absent → `gating.onMissingEstimate` (default `run`, fail-safe
+ *    to thoroughness).
+ */
+export function shouldRunGatedStep(estimate, gating) {
+    if (!gating || !gating.enabled)
+        return true;
+    if (!estimate)
+        return (gating.onMissingEstimate ?? 'run') === 'run';
+    const axes = [
+        [gating.minComplexity, estimate.complexity],
+        [gating.minRisk, estimate.risk],
+        [gating.minImpact, estimate.impact],
+    ];
+    for (const [threshold, value] of axes) {
+        if (threshold !== undefined && value >= threshold)
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=stepGating.logic.js.map

package/dist/modules/execution/stepGating.logic.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stepGating.logic.js","sourceRoot":"","sources":["../../../src/modules/execution/stepGating.logic.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,QAAyC,EACzC,MAAqC;IAErC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO,IAAI,CAAA;IAC3C,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,MAAM,CAAC,iBAAiB,IAAI,KAAK,CAAC,KAAK,KAAK,CAAA;IACnE,MAAM,IAAI,GAAwC;QAChD,CAAC,MAAM,CAAC,aAAa,EAAE,QAAQ,CAAC,UAAU,CAAC;QAC3C,CAAC,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC;QAC/B,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC;KACpC,CAAA;IACD,KAAK,MAAM,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,IAAI,EAAE,CAAC;QACtC,IAAI,SAAS,KAAK,SAAS,IAAI,KAAK,IAAI,SAAS;YAAE,OAAO,IAAI,CAAA;IAChE,CAAC;IACD,OAAO,KAAK,CAAA;AACd,CAAC"}

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

@@ -0,0 +1,41 @@
+import type { AgentRunResult, ExecutionInstance, PipelineStep } from '@cat-factory/kernel';
+/** Context handed to a step-completion resolver after its step's agent finished. */
+export interface StepResolverContext {
+    workspaceId: string;
+    instance: ExecutionInstance;
+    step: PipelineStep;
+    /** The finished agent's structured result (the resolver acts on it mechanically). */
+    result: AgentRunResult;
+    /** Whether this step is the pipeline's last (resolvers rarely need it). */
+    isFinalStep: boolean;
+}
+/** The outcome of a post-completion resolver. */
+export interface StepResolution {
+    /** Replacement step output (e.g. a human-readable merge summary). */
+    output?: string;
+    /**
+     * Set when the resolver has already decided the block's TERMINAL status itself (the
+     * merger flips the block to `done` on a real merge or `pr_ready` on a review). The
+     * engine's `finalizeBlock` then only backstops a block the resolver left untouched.
+     */
+    ownsTerminalStatus?: boolean;
+}
+/**
+ * Deterministic backend logic run after an agent step completes, keyed by `agentKind`.
+ * Registered in {@link ExecutionService} (see `buildStepResolverRegistry`); the engine
+ * runs the matching resolver in `recordStepResult` once the step's agent has finished,
+ * regardless of the step's position in the pipeline.
+ */
+export interface StepCompletionResolver {
+    /** Matches the step's `agentKind` (e.g. `merger`). */
+    kind: string;
+    /**
+     * Whether this resolver applies to the finished step's result — lets a resolver no-op
+     * when its agent produced nothing to act on (e.g. the merger returned no assessment).
+     * Defaults to always-applies when omitted.
+     */
+    applies?(result: AgentRunResult): boolean;
+    /** Run the mechanical post-completion logic. */
+    resolve(ctx: StepResolverContext): Promise<StepResolution | void>;
+}
+//# sourceMappingURL=stepResolvers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"stepResolvers.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/stepResolvers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAqB1F,oFAAoF;AACpF,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,IAAI,EAAE,YAAY,CAAA;IAClB,qFAAqF;IACrF,MAAM,EAAE,cAAc,CAAA;IACtB,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAA;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAA;IACZ;;;;OAIG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAA;IACzC,gDAAgD;IAChD,OAAO,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAAA;CAClE"}