@cat-factory/orchestration 0.37.0 → 0.37.2

package/dist/modules/execution/RunStateMachine.js

@@ -0,0 +1,389 @@
+import { isAsyncAgentExecutor } from '@cat-factory/kernel';
+import { MERGER_AGENT_KIND } from './ci.logic.js';
+/**
+ * "What to do next" guidance per failure kind a pipeline run can produce, shown
+ * under the failure banner on the board (mirrors bootstrap's FAILURE_HINTS). Only
+ * the execution-relevant subset of {@link AgentFailureKind} is keyed.
+ */
+const EXECUTION_FAILURE_HINTS = {
+    agent: 'An agent step failed after its automatic retries. Review the run, then retry to re-run the pipeline.',
+    job_failed: 'The implementation container reported a failure. Inspect its logs (Cloudflare Workers Observability, filtered by the run id), then retry to spin a fresh container.',
+    evicted: 'The implementation container kept vanishing mid-run even after automatic fresh-container restarts. Most often this is transient: a deploy / new-version rollout draining the container, in which case simply retrying once the rollout has finished succeeds. If it persists, it points at a memory or crash issue on the run — inspect its logs (Cloudflare Workers Observability, filtered by the run id) and consider a heavier container instance type. Retry to try again.',
+    timeout: 'The run exceeded its time budget — a step or the implementation job did not finish in time. Retry to start it again.',
+    rejected: 'You rejected this step’s proposal, stopping the run. Retry to re-run the pipeline from the rejected step.',
+    companion_rejected: 'A companion agent could not return a usable quality assessment (its reply was truncated or malformed) even after a repair retry. Review the companion’s raw output on the run, then retry.',
+    cancelled: 'You stopped this run; its container was killed. Retry to start it again.',
+    dispatch: 'The agent’s container could not be started — the run never began executing. The provider/runtime’s verbatim response is shown below. Most often this is transient (a capacity blip or a new-version rollout); retrying spins a fresh container. If it persists it points at a misconfigured container binding/image or runner pool. Retry to try again.',
+    unknown: 'The run failed for an unclassified reason. Review the run, then retry.',
+};
+/**
+ * The async instance/block state-machine spine of the execution engine — the outer layer
+ * over {@link StepGraph}. It owns everything the engine and every gate controller share
+ * about MOVING a run: persisting the instance, pushing the live event (with the metrics
+ * rollup + terminal-state cleanup), the block status/progress writes, parking on a decision
+ * and advancing past a resolved one, finalizing a finished pipeline, failing a run, and
+ * reclaiming the per-run container.
+ *
+ * Lifted verbatim out of `ExecutionService` so these primitives have ONE cohesive home
+ * instead of being scattered as private methods and handed to each controller as a fat
+ * callback bag. The merge/auto-start subgraph (`finalizeMerge` / `applyModuleAssignment` /
+ * `autoStartDependents`) deliberately stays on the engine — `finalizeBlock` here only flips
+ * status and raises the no-merger notification, so this layer carries no merge collaborators.
+ */
+export class RunStateMachine {
+    executionRepository;
+    blockRepository;
+    events;
+    workRunner;
+    agentExecutor;
+    idGenerator;
+    clock;
+    stepGraph;
+    notificationService;
+    kaizenScheduler;
+    subscriptionActivations;
+    llmObservability;
+    constructor(deps) {
+        this.executionRepository = deps.executionRepository;
+        this.blockRepository = deps.blockRepository;
+        this.events = deps.events;
+        this.workRunner = deps.workRunner;
+        this.agentExecutor = deps.agentExecutor;
+        this.idGenerator = deps.idGenerator;
+        this.clock = deps.clock;
+        this.stepGraph = deps.stepGraph;
+        this.notificationService = deps.notificationService;
+        this.kaizenScheduler = deps.kaizenScheduler;
+        this.subscriptionActivations = deps.subscriptionActivations;
+        this.llmObservability = deps.llmObservability;
+    }
+    /** Persist the instance (the single write seam shared by the engine + controllers). */
+    persistInstance(workspaceId, instance) {
+        return this.executionRepository.upsert(workspaceId, instance);
+    }
+    async emitInstance(workspaceId, instance) {
+        // Stamp each step with the run id so a lone step (in a pushed event, a log line, a
+        // detail view) is self-describing for debugging; the value always equals the run id.
+        for (const step of instance.steps)
+            step.runId = instance.id;
+        // The metrics rollup and the block fetch are independent, so run them concurrently
+        // — the rollup adds no serial latency to the (frequent) emit path.
+        const [, block] = await Promise.all([
+            this.attachStepMetrics(workspaceId, instance),
+            this.blockRepository.get(workspaceId, instance.blockId),
+        ]);
+        await this.events.executionChanged(workspaceId, instance, block);
+        // When a run reaches a terminal state, schedule a post-run Kaizen grading for each
+        // completed agent step (the scheduler skips verified combos + already-graded steps).
+        // Best-effort + idempotent: a failure here must never derail the emit, and a re-emit
+        // of an already-scheduled run is a no-op. The actual LLM grading runs later in the
+        // background sweep, so this only does cheap inserts.
+        if (this.kaizenScheduler && (instance.status === 'done' || instance.status === 'failed')) {
+            try {
+                await this.kaizenScheduler.scheduleForRun(workspaceId, instance);
+            }
+            catch {
+                // Swallow — grading is an observability concern and must never break a run.
+            }
+        }
+        // When a run reaches a terminal state, delete its per-run personal-credential
+        // activation immediately (individual-usage subscriptions) so the system-encrypted
+        // token copy doesn't linger to its TTL. Best-effort + idempotent — a missing repo or
+        // a re-emit of an already-cleared run is a no-op, and a failure here must never
+        // derail the emit.
+        if (this.subscriptionActivations &&
+            (instance.status === 'done' || instance.status === 'failed')) {
+            try {
+                await this.subscriptionActivations.deleteByExecution(instance.id);
+            }
+            catch {
+                // Swallow — a failure here must never derail the emit. This is not a silent
+                // data-loss path: the TTL sweep reclaims the row as a backstop, and the sweep
+                // (Worker cron / Node retention timer) logs its own errors, so a *systemic*
+                // cleanup failure surfaces there rather than being lost here.
+            }
+        }
+    }
+    /**
+     * Roll the run's recorded LLM calls into per-step `metrics` for the board, in
+     * place on the emitted instance. The proxy keys calls by execution + agentKind
+     * (not step index), so the aggregate is per-agent-kind within the run; steps
+     * sharing a kind get the same rollup. Best-effort and a no-op when the sink is
+     * not wired, so it never blocks an emit.
+     */
+    async attachStepMetrics(workspaceId, instance) {
+        if (!this.llmObservability)
+            return;
+        try {
+            const summaries = await this.llmObservability.summarizeByExecution(workspaceId, instance.id);
+            if (summaries.length === 0)
+                return;
+            const byKind = new Map(summaries.map((s) => [s.agentKind, s]));
+            for (const step of instance.steps) {
+                const s = byKind.get(step.agentKind);
+                if (!s)
+                    continue;
+                step.metrics = {
+                    calls: s.calls,
+                    promptTokens: s.promptTokens,
+                    cachedPromptTokens: s.cachedPromptTokens,
+                    completionTokens: s.completionTokens,
+                    peakCompletionTokens: s.peakCompletionTokens,
+                    maxOutputTokens: s.maxOutputTokens,
+                    truncatedCalls: s.truncatedCalls,
+                    upstreamMs: s.upstreamMs,
+                    overheadMs: s.overheadMs,
+                    errors: s.errors,
+                    warnings: s.warnings,
+                };
+            }
+        }
+        catch (error) {
+            // Observability is best-effort; never block an emit on a metrics read.
+            void error;
+        }
+    }
+    /** Set the block's in-progress/blocked status and step-completion progress. */
+    async updateBlockProgress(workspaceId, instance, status) {
+        const total = instance.steps.length || 1;
+        const done = instance.steps.filter((s) => s.state === 'done').length;
+        await this.blockRepository.update(workspaceId, instance.blockId, {
+            status,
+            progress: Math.min(1, done / total),
+        });
+    }
+    /**
+     * Advance the block's step PROGRESS without touching its status — used when a step
+     * resolver already owns the block's terminal status (the merger set `done`/`pr_ready`)
+     * and a trailing step still follows, so the bar moves on without downgrading that status.
+     */
+    async refreshBlockProgress(workspaceId, instance) {
+        const total = instance.steps.length || 1;
+        const done = instance.steps.filter((s) => s.state === 'done').length;
+        await this.blockRepository.update(workspaceId, instance.blockId, {
+            progress: Math.min(1, done / total),
+        });
+    }
+    /**
+     * Park a step on a human approval decision: mint the approval id, freeze the step's
+     * duration clock, flip the run `blocked`, persist + emit, and return the durable
+     * `awaiting_decision` outcome the driver parks on.
+     */
+    async parkStepOnDecision(workspaceId, instance, step, proposal = '') {
+        step.approval = { id: this.idGenerator.next('appr'), status: 'pending', proposal };
+        this.stepGraph.pauseStepForInput(step);
+        instance.status = 'blocked';
+        await this.updateBlockProgress(workspaceId, instance, 'blocked');
+        await this.executionRepository.upsert(workspaceId, instance);
+        await this.emitInstance(workspaceId, instance);
+        return { kind: 'awaiting_decision', decisionId: step.approval.id };
+    }
+    /**
+     * Finish a gate step whose decision a human resolved and advance the run: stamp the step
+     * done, finalize the block (final step) or start the next, persist, signal the durable
+     * driver that the decision is `approved`, and emit.
+     */
+    async advancePastResolvedGate(workspaceId, instance, stepIndex) {
+        const step = instance.steps[stepIndex];
+        const decisionId = step.approval.id;
+        this.stepGraph.finishStep(step);
+        step.progress = 1;
+        const isFinalStep = stepIndex === instance.steps.length - 1;
+        if (isFinalStep) {
+            instance.status = 'done';
+            await this.finalizeBlock(workspaceId, instance, undefined);
+            await this.stopRunContainer(workspaceId, instance);
+        }
+        else {
+            instance.currentStep = stepIndex + 1;
+            const next = instance.steps[instance.currentStep];
+            if (next)
+                this.stepGraph.startStep(next);
+            if (instance.status === 'blocked')
+                instance.status = 'running';
+            await this.updateBlockProgress(workspaceId, instance, 'in_progress');
+        }
+        await this.executionRepository.upsert(workspaceId, instance);
+        await this.workRunner.signalDecision(workspaceId, instance.id, decisionId, 'approved');
+        await this.emitInstance(workspaceId, instance);
+    }
+    /**
+     * A pipeline finished. A frame becomes `done` (a mapping-only run leaves it
+     * `ready`). A *task* never auto-`done`s from a confidence score any more — that
+     * looked merged when the PR was still open with red CI. Instead:
+     *   - if the pipeline has a `merger` step, it already owned the merge/notify
+     *     decision (see `resolveMergerStep`); we only backstop a missing one;
+     *   - otherwise the work is complete but unmerged: leave the PR open (`pr_ready`)
+     *     and raise a `pipeline_complete` notification for a human to confirm + merge.
+     * `done` now strictly means the PR was merged (see the engine's `finalizeMerge`).
+     */
+    async finalizeBlock(workspaceId, instance, confidence) {
+        const block = await this.blockRepository.get(workspaceId, instance.blockId);
+        if (!block || block.status === 'done')
+            return;
+        if ((block.level ?? 'frame') !== 'task') {
+            // A mapping-only run (just the `blueprints` step, e.g. kicked off after a
+            // bootstrap) leaves the service frame `ready` and droppable rather than
+            // marking the whole service "done".
+            const mappingOnly = instance.steps.every((s) => s.agentKind === 'blueprints');
+            await this.blockRepository.update(workspaceId, block.id, {
+                status: mappingOnly ? 'ready' : 'done',
+                progress: 1,
+            });
+            return;
+        }
+        // Confidence is recorded by the caller (recordStepResult) before any merge, so
+        // it persists on both the merge and review paths; `confidence` is unused here.
+        void confidence;
+        const hasMerger = instance.steps.some((s) => s.agentKind === MERGER_AGENT_KIND);
+        if (hasMerger) {
+            // The `merger` step already merged (→ `done`) or raised a review (→ `pr_ready`).
+            // Only backstop the case where it produced no decision at all.
+            const fresh = await this.blockRepository.get(workspaceId, block.id);
+            if (fresh && fresh.status !== 'done' && fresh.status !== 'pr_ready') {
+                await this.blockRepository.update(workspaceId, block.id, {
+                    status: 'pr_ready',
+                    progress: 1,
+                });
+            }
+            return;
+        }
+        // No merger in this pipeline: complete but unmerged — ask a human to confirm.
+        await this.blockRepository.update(workspaceId, block.id, { status: 'pr_ready', progress: 1 });
+        await this.raisePipelineComplete(workspaceId, instance, block);
+    }
+    async raisePipelineComplete(workspaceId, instance, block) {
+        if (!this.notificationService)
+            return;
+        await this.notificationService.raise(workspaceId, {
+            type: 'pipeline_complete',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `Confirm "${block.title}" is complete`,
+            body: `The "${instance.pipelineName}" pipeline finished and opened a PR, but it has no ` +
+                `merger step. Review the work and confirm it as complete (this merges the PR).`,
+            payload: {
+                ...(block.pullRequest?.url ? { prUrl: block.pullRequest.url } : {}),
+                pipelineName: instance.pipelineName,
+            },
+        });
+    }
+    /**
+     * Record a terminal failure on a run: reclaim its container, mark it `failed` with the
+     * richest failure record (first write wins), drop the block to `blocked` with the
+     * progress it reached, and emit. The single funnel for every failure kind.
+     */
+    async failRun(workspaceId, executionId, message, kind = 'agent', detail = null) {
+        const instance = await this.executionRepository.get(workspaceId, executionId);
+        if (!instance)
+            return;
+        // Reclaim the per-run container on the failure path too: a failed run otherwise
+        // leaves its container to idle out sleepAfter. This is the single funnel for
+        // every failure kind (job_failed from the driver, the spend/decision timeouts,
+        // and the user-facing stopRun, which already reclaimed — the call is idempotent).
+        await this.stopRunContainer(workspaceId, instance);
+        // The FIRST recorded failure wins: a run already in a terminal `failed` state keeps
+        // its existing (richest) failure rather than being overwritten. An inline gate that
+        // knows the precise kind/detail returns a `job_failed` result the driver funnels here,
+        // so there should only ever be one write — but this guards against a future path that
+        // both records a failure and returns `job_failed`, which would otherwise clobber the
+        // good record with a generic one (the companion-rejected regression).
+        if (instance.status === 'failed')
+            return;
+        const failure = {
+            kind,
+            message,
+            detail,
+            hint: EXECUTION_FAILURE_HINTS[kind] ?? null,
+            occurredAt: this.clock.now(),
+            lastSubtasks: instance.steps[instance.currentStep]?.subtasks ?? null,
+        };
+        await this.executionRepository.markFailed(workspaceId, executionId, failure);
+        // Progress reflects how far the pipeline got before failing.
+        const done = instance.steps.filter((s) => s.state === 'done').length;
+        const progress = instance.steps.length > 0 ? done / instance.steps.length : 0;
+        await this.blockRepository.update(workspaceId, instance.blockId, {
+            status: 'blocked',
+            progress,
+        });
+        const failed = await this.executionRepository.get(workspaceId, executionId);
+        if (failed)
+            await this.emitInstance(workspaceId, failed);
+    }
+    /** Reclaim the per-run container (per-job backends cancel the parked job; run-container
+     * backends use the run id). Best-effort: a vanished container is nothing to reclaim. */
+    async stopRunContainer(workspaceId, instance) {
+        const executor = this.agentExecutor;
+        if (!isAsyncAgentExecutor(executor) || !executor.stopJob)
+            return;
+        // The in-flight step's job id (when a job is parked), so a per-job backend can
+        // cancel exactly it; the run-container backends ignore it and use the run id.
+        const jobId = instance.steps[instance.currentStep]?.jobId ?? instance.id;
+        try {
+            await executor.stopJob({ jobId, runId: instance.id, workspaceId });
+        }
+        catch {
+            // The container may already be gone (eviction/completion) — nothing to reclaim.
+        }
+    }
+    /** Raise the iteration-cap `decision_required` card when a review loop parks at its cap. */
+    async raiseDecisionRequired(workspaceId, instance) {
+        if (!this.notificationService)
+            return;
+        const block = await this.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return;
+        await this.notificationService.raise(workspaceId, {
+            type: 'decision_required',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `"${block.title}" ran out of automatic iterations and needs your decision`,
+            body: 'An automatic review loop reached its iteration cap without converging. Open the ' +
+                'task to choose: one more round, proceed with the current result, or stop and reset.',
+            payload: { pipelineName: instance.pipelineName },
+        });
+    }
+    /**
+     * Ensure an open notification exists for a run that has just parked waiting for a human
+     * (an agent-raised decision, an approval gate, or an iterative review gate). Without
+     * the old decision timeout the run waits indefinitely, so the inbox card — which the
+     * periodic sweep escalates yellow → red — is the only signal a human is needed.
+     *
+     * Non-clobbering: if ANY open notification is already on the block (a more specific
+     * `merge_review`, iteration-cap `decision_required`, etc.), it is left untouched and we
+     * raise nothing — so the richer message wins. Best-effort: no notification service
+     * (tests) or a missing block is a no-op.
+     */
+    async ensureWaitingNotification(workspaceId, instance) {
+        const svc = this.notificationService;
+        if (!svc)
+            return;
+        const open = await svc.listOpen(workspaceId);
+        if (open.some((n) => n.blockId === instance.blockId))
+            return;
+        const block = await this.blockRepository.get(workspaceId, instance.blockId);
+        if (!block)
+            return;
+        await svc.raise(workspaceId, {
+            type: 'decision_required',
+            blockId: block.id,
+            executionId: instance.id,
+            title: `"${block.title}" is waiting for your input`,
+            body: 'A pipeline step is parked awaiting a human decision. Open the task to respond.',
+            payload: { pipelineName: instance.pipelineName },
+        });
+    }
+    /**
+     * Clear the auto-raised "waiting for a human decision" card once a run advances past
+     * the decision it was parked on (so the escalation sweep can't flip a settled decision
+     * red). Scoped to the `decision_required` type, so the human-actionable cards a stopped
+     * run leaves behind are untouched. Best-effort: no notification service (tests) is a no-op.
+     */
+    async clearWaitingNotification(workspaceId, instance) {
+        const svc = this.notificationService;
+        if (!svc)
+            return;
+        await svc.clearWaitingDecision(workspaceId, instance.blockId);
+    }
+}
+//# sourceMappingURL=RunStateMachine.js.map

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

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

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

@@ -0,0 +1,70 @@
+import type { Clock, ExecutionInstance, PipelineStep } from '@cat-factory/kernel';
+/**
+ * The pure, synchronous step/cursor mutators of the execution engine — the dependency-free
+ * inner layer of the run state-machine spine. Every method operates on a passed
+ * {@link PipelineStep} / {@link ExecutionInstance} and mutates it in place; the only
+ * collaborator is the {@link Clock} the timing stamps come from. Lifted verbatim out of
+ * `ExecutionService` so the engine AND every gate controller share ONE definition of "what
+ * does it mean to start / finish / park / reset a step" instead of each receiving the
+ * mutators as a loose callback bag.
+ *
+ * Deliberately holds NO repositories, event publisher or runner — those async,
+ * instance-persisting concerns live in {@link RunStateMachine}, which composes this. Keeping
+ * the pure mutators separate is what lets a controller depend on the timing rules without
+ * pulling in the whole persistence/emission surface.
+ */
+export declare class StepGraph {
+    private readonly clock;
+    constructor(clock: Clock);
+    /** Transition a step into `working`, stamping its start time once, and resume its clock. */
+    startStep(step: PipelineStep): void;
+    /**
+     * Transition a step into `done`, stamping its finish time once. Set-once so the
+     * approval-gate flow (which re-asserts `done` after a human approves, long after
+     * the agent actually finished) keeps the agent's true completion time, and so a
+     * replay doesn't move it. With {@link startStep}'s `startedAt` this yields the
+     * step's execution duration. A step finished directly out of a parked approval
+     * stopped *working* when it parked, so its duration is billed to the pause instant
+     * ({@link pauseStepForInput}), not the (later) moment the human decided.
+     */
+    finishStep(step: PipelineStep): void;
+    /**
+     * Park a step on a human decision and freeze its duration clock. Records when the
+     * step stopped working (`pausedAt`) so elapsed time no longer accrues while it waits
+     * for input — the symmetric counterpart of the terminal freeze on `finishedAt`.
+     * Set-once (a Workflows replay re-parking keeps the original instant); cleared when
+     * the step resumes ({@link startStep}) or finishes ({@link finishStep}).
+     */
+    pauseStepForInput(step: PipelineStep): void;
+    /**
+     * Reset a step so the durable driver re-runs it from scratch: clear its live container
+     * job handle (so it dispatches FRESH work rather than re-attaching to a stale/evicted
+     * job), timings, approval, subtasks and prior output.
+     */
+    resetStepForRerun(step: PipelineStep): void;
+    /**
+     * Loop a producer step back for rework and re-run every step from it up to and
+     * including the companion at `companionIndex`: each one is reset (crucially clearing
+     * stale container job handles so an intermediate container step re-dispatches fresh
+     * work instead of re-attaching to its evicted job), the producer is handed the
+     * `rework` feedback + started, and the instance cursor is moved back to the producer.
+     * Shared by the automatic companion loop and the human "request changes" path.
+     */
+    rerunProducerThrough(instance: ExecutionInstance, producerIndex: number, companionIndex: number, rework: NonNullable<PipelineStep['rework']>): void;
+    /**
+     * The index of the nearest preceding step a companion grades (one of its target
+     * producer kinds), or -1 when none precedes it. The single producer-search used by the
+     * automatic companion loop, the human "request changes" redirect, and the iteration-cap
+     * extra-round resolution.
+     */
+    companionProducerIndex(instance: ExecutionInstance, companionIndex: number): number;
+    /**
+     * Loop a companion's producer back for one more automatic rework cycle: charge one
+     * attempt against the budget, then re-run the producer (and any intermediate steps) up
+     * to and including the companion so it re-grades. Shared by the automatic
+     * below-threshold loop and the human-granted extra round, so both consume the budget
+     * identically.
+     */
+    loopCompanionProducer(instance: ExecutionInstance, companionIndex: number, rework: NonNullable<PipelineStep['rework']>): void;
+}
+//# sourceMappingURL=StepGraph.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"StepGraph.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/StepGraph.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAGjF;;;;;;;;;;;;;GAaG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,KAAK;IAAlC,YAA6B,KAAK,EAAE,KAAK,EAAI;IAE7C,4FAA4F;IAC5F,SAAS,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAMlC;IAED;;;;;;;;OAQG;IACH,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAInC;IAED;;;;;;OAMG;IACH,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAG1C;IAED;;;;OAIG;IACH,iBAAiB,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAc1C;IAED;;;;;;;OAOG;IACH,oBAAoB,CAClB,QAAQ,EAAE,iBAAiB,EAC3B,aAAa,EAAE,MAAM,EACrB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,GAC1C,IAAI,CAQN;IAED;;;;;OAKG;IACH,sBAAsB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,GAAG,MAAM,CAMlF;IAED;;;;;;OAMG;IACH,qBAAqB,CACnB,QAAQ,EAAE,iBAAiB,EAC3B,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,GAC1C,IAAI,CAMN;CACF"}

package/dist/modules/execution/StepGraph.js

@@ -0,0 +1,124 @@
+import { companionTargets } from '@cat-factory/agents';
+/**
+ * The pure, synchronous step/cursor mutators of the execution engine — the dependency-free
+ * inner layer of the run state-machine spine. Every method operates on a passed
+ * {@link PipelineStep} / {@link ExecutionInstance} and mutates it in place; the only
+ * collaborator is the {@link Clock} the timing stamps come from. Lifted verbatim out of
+ * `ExecutionService` so the engine AND every gate controller share ONE definition of "what
+ * does it mean to start / finish / park / reset a step" instead of each receiving the
+ * mutators as a loose callback bag.
+ *
+ * Deliberately holds NO repositories, event publisher or runner — those async,
+ * instance-persisting concerns live in {@link RunStateMachine}, which composes this. Keeping
+ * the pure mutators separate is what lets a controller depend on the timing rules without
+ * pulling in the whole persistence/emission surface.
+ */
+export class StepGraph {
+    clock;
+    constructor(clock) {
+        this.clock = clock;
+    }
+    /** Transition a step into `working`, stamping its start time once, and resume its clock. */
+    startStep(step) {
+        step.state = 'working';
+        if (step.startedAt == null)
+            step.startedAt = this.clock.now();
+        // (Re)entering `working` means the step is no longer parked on a human: resume
+        // its duration clock (see {@link pauseStepForInput}).
+        step.pausedAt = null;
+    }
+    /**
+     * Transition a step into `done`, stamping its finish time once. Set-once so the
+     * approval-gate flow (which re-asserts `done` after a human approves, long after
+     * the agent actually finished) keeps the agent's true completion time, and so a
+     * replay doesn't move it. With {@link startStep}'s `startedAt` this yields the
+     * step's execution duration. A step finished directly out of a parked approval
+     * stopped *working* when it parked, so its duration is billed to the pause instant
+     * ({@link pauseStepForInput}), not the (later) moment the human decided.
+     */
+    finishStep(step) {
+        step.state = 'done';
+        if (step.finishedAt == null)
+            step.finishedAt = step.pausedAt ?? this.clock.now();
+        step.pausedAt = null;
+    }
+    /**
+     * Park a step on a human decision and freeze its duration clock. Records when the
+     * step stopped working (`pausedAt`) so elapsed time no longer accrues while it waits
+     * for input — the symmetric counterpart of the terminal freeze on `finishedAt`.
+     * Set-once (a Workflows replay re-parking keeps the original instant); cleared when
+     * the step resumes ({@link startStep}) or finishes ({@link finishStep}).
+     */
+    pauseStepForInput(step) {
+        step.state = 'waiting_decision';
+        if (step.pausedAt == null)
+            step.pausedAt = this.clock.now();
+    }
+    /**
+     * Reset a step so the durable driver re-runs it from scratch: clear its live container
+     * job handle (so it dispatches FRESH work rather than re-attaching to a stale/evicted
+     * job), timings, approval, subtasks and prior output.
+     */
+    resetStepForRerun(step) {
+        step.state = 'pending';
+        step.startedAt = null;
+        step.finishedAt = null;
+        step.pausedAt = null;
+        step.jobId = undefined;
+        step.approval = null;
+        step.subtasks = undefined;
+        step.progress = 0;
+        step.output = undefined;
+        // Drop the prior run's structured output too, so a re-run that produces no `custom`
+        // doesn't leave stale JSON for the `generic-structured` result view to render.
+        step.custom = undefined;
+        step.rework = undefined;
+    }
+    /**
+     * Loop a producer step back for rework and re-run every step from it up to and
+     * including the companion at `companionIndex`: each one is reset (crucially clearing
+     * stale container job handles so an intermediate container step re-dispatches fresh
+     * work instead of re-attaching to its evicted job), the producer is handed the
+     * `rework` feedback + started, and the instance cursor is moved back to the producer.
+     * Shared by the automatic companion loop and the human "request changes" path.
+     */
+    rerunProducerThrough(instance, producerIndex, companionIndex, rework) {
+        for (let i = producerIndex; i <= companionIndex; i++) {
+            this.resetStepForRerun(instance.steps[i]);
+        }
+        const producer = instance.steps[producerIndex];
+        producer.rework = rework;
+        this.startStep(producer);
+        instance.currentStep = producerIndex;
+    }
+    /**
+     * The index of the nearest preceding step a companion grades (one of its target
+     * producer kinds), or -1 when none precedes it. The single producer-search used by the
+     * automatic companion loop, the human "request changes" redirect, and the iteration-cap
+     * extra-round resolution.
+     */
+    companionProducerIndex(instance, companionIndex) {
+        const targets = companionTargets(instance.steps[companionIndex].agentKind);
+        for (let i = companionIndex - 1; i >= 0; i--) {
+            if (targets.includes(instance.steps[i].agentKind))
+                return i;
+        }
+        return -1;
+    }
+    /**
+     * Loop a companion's producer back for one more automatic rework cycle: charge one
+     * attempt against the budget, then re-run the producer (and any intermediate steps) up
+     * to and including the companion so it re-grades. Shared by the automatic
+     * below-threshold loop and the human-granted extra round, so both consume the budget
+     * identically.
+     */
+    loopCompanionProducer(instance, companionIndex, rework) {
+        const companionStep = instance.steps[companionIndex];
+        const producerIndex = this.companionProducerIndex(instance, companionIndex);
+        companionStep.companion.attempts += 1;
+        this.rerunProducerThrough(instance, producerIndex, companionIndex, rework);
+        if (instance.status === 'blocked')
+            instance.status = 'running';
+    }
+}
+//# sourceMappingURL=StepGraph.js.map

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

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

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

@@ -2,6 +2,7 @@ import type { AgentExecutor, AgentRunResult, Block, BlockRepository, ExecutionIn
 import type { NotificationService } from '../notifications/NotificationService.js';
 import type { AdvanceResult } from './advance.js';
 import type { AgentContextBuilder } from './AgentContextBuilder.js';
+import type { RunStateMachine } from './RunStateMachine.js';
 /** The engine collaborators the Tester gate drives (kept on the engine, injected here). */
 export interface TesterControllerDeps {
     blockRepository: BlockRepository;
@@ -12,10 +13,8 @@ export interface TesterControllerDeps {
     resolveMergePreset: (workspaceId: string, block: Block) => Promise<{
         ciMaxAttempts: number;
     }>;
-    /** Reclaim the run's finished container before dispatching the next job. */
-    stopRunContainer: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
-    persistInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
-    emitInstance: (workspaceId: string, instance: ExecutionInstance) => Promise<void>;
+    /** The async instance/block spine (container reclaim, instance persist + emit). */
+    stateMachine: RunStateMachine;
 }
 /**
  * Drives the Tester gate's fix loop: apply a Tester report to its step (greenlight →

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

@@ -1 +1 @@
-{"version":3,"file":"TesterController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/TesterController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAEb,cAAc,EACd,KAAK,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAI5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAA;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AA4CnE,2FAA2F;AAC3F,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,eAAe,CAAA;IAChC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;IACzC,aAAa,EAAE,aAAa,CAAA;IAC5B,cAAc,EAAE,mBAAmB,CAAA;IACnC,0EAA0E;IAC1E,kBAAkB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC7F,4EAA4E;IAC5E,gBAAgB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACrF,eAAe,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACpF,YAAY,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;CAClF;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,oBAAoB,EAAI;IAE3D;;;;;;OAMG;IACG,mBAAmB,CACvB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA+D/B;IAED;;;OAGG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,aAAa,CAAC,CAsBxB;IAED;;;;;OAKG;YACW,UAAU;IAkBxB,wEAAwE;YAC1D,eAAe;IAuB7B;;;;;OAKG;YACW,aAAa;CA0D5B"}
+{"version":3,"file":"TesterController.d.ts","sourceRoot":"","sources":["../../../src/modules/execution/TesterController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,aAAa,EAEb,cAAc,EACd,KAAK,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,EACb,MAAM,qBAAqB,CAAA;AAI5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAA;AAClF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAA;AACnE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AA4C3D,2FAA2F;AAC3F,MAAM,WAAW,oBAAoB;IACnC,eAAe,EAAE,eAAe,CAAA;IAChC,mBAAmB,CAAC,EAAE,mBAAmB,CAAA;IACzC,aAAa,EAAE,aAAa,CAAA;IAC5B,cAAc,EAAE,mBAAmB,CAAA;IACnC,0EAA0E;IAC1E,kBAAkB,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC;QAAE,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC7F,mFAAmF;IACnF,YAAY,EAAE,eAAe,CAAA;CAC9B;AAED;;;;;;;GAOG;AACH,qBAAa,gBAAgB;IACf,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,oBAAoB,EAAI;IAE3D;;;;;;OAMG;IACG,mBAAmB,CACvB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,cAAc,GACrB,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CA+D/B;IAED;;;OAGG;IACG,cAAc,CAClB,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,iBAAiB,EAC3B,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,aAAa,CAAC,CAsBxB;IAED;;;;;OAKG;YACW,UAAU;IAkBxB,wEAAwE;YAC1D,eAAe;IAuB7B;;;;;OAKG;YACW,aAAa;CA0D5B"}