@cat-factory/orchestration 0.6.0

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

@@ -0,0 +1,874 @@
+import type { AgentFailureKind, Block, BlueprintService, CiStatusProvider, ExecutionInstance, MergePresetRepository, PullRequestMerger, PullRequestMergeabilityProvider, ReleaseHealthProvider, IncidentEnrichmentProvider, StepReviewComment, SubscriptionActivationRepository, TicketTrackerProvider } from '@cat-factory/kernel';
+import { type HasPersonalSubscription } from './individualVendors.logic.js';
+import { type ProviderCapabilities, type SubscriptionVendor } from '@cat-factory/kernel';
+import type { NotificationService } from '../notifications/NotificationService.js';
+import type { WorkspaceSettingsService } from '../settings/WorkspaceSettingsService.js';
+import type { RequirementReviewService } from '../requirements/RequirementReviewService.js';
+import type { ClarityReviewService } from '../clarity/ClarityReviewService.js';
+import type { IterationCapChoice, RequirementReview, ClarityReview, ResolveRequirementsExceededChoice } from '@cat-factory/kernel';
+import type { LlmObservabilityService } from '../observability/LlmObservabilityService.js';
+import type { AccountRepository, BlockRepository, ExecutionRepository, PipelineRepository, WorkspaceRepository } from '@cat-factory/kernel';
+import type { Clock, IdGenerator } from '@cat-factory/kernel';
+import type { AgentExecutor } from '@cat-factory/kernel';
+import type { WorkRunner } from '@cat-factory/kernel';
+import type { ExecutionEventPublisher } from '@cat-factory/kernel';
+import type { DocumentRepository } from '@cat-factory/kernel';
+import type { TaskRepository } from '@cat-factory/kernel';
+import type { RequirementReviewRepository } from '@cat-factory/kernel';
+import type { ClarityReviewRepository } from '@cat-factory/kernel';
+import type { EnvironmentProvisioningService } from '@cat-factory/integrations';
+import type { BoardService } from '../board/BoardService.js';
+import type { SpendService } from '@cat-factory/spend';
+import type { AdvanceOptions, AdvanceResult } from './advance.js';
+export interface ExecutionServiceDependencies {
+    workspaceRepository: WorkspaceRepository;
+    blockRepository: BlockRepository;
+    pipelineRepository: PipelineRepository;
+    executionRepository: ExecutionRepository;
+    /**
+     * Resolves the owning account of a workspace so a service that pins no cloud
+     * provider falls back to the account's `defaultCloudProvider` at dispatch.
+     */
+    accountRepository: AccountRepository;
+    idGenerator: IdGenerator;
+    clock: Clock;
+    agentExecutor: AgentExecutor;
+    workRunner: WorkRunner;
+    executionEventPublisher: ExecutionEventPublisher;
+    boardService: BoardService;
+    spendService: SpendService;
+    /**
+     * Optional: when the document-source integration is configured, documents
+     * linked to a block are resolved here and fed to the agent as extra context.
+     */
+    documentRepository?: DocumentRepository;
+    /**
+     * Optional: when the task-source integration is configured, tracker issues
+     * linked to a block are resolved here and fed to the agent as extra context.
+     */
+    taskRepository?: TaskRepository;
+    /**
+     * Optional: when the requirements-review feature is configured, a block's
+     * reworked ("incorporated") requirements are read here. When present they REPLACE
+     * the block's description + linked docs/tasks as the agent context (for every
+     * step) and become the per-task input the spec-writer aggregates. Absent
+     * → the engine uses the original description + docs/tasks unchanged.
+     */
+    requirementReviewRepository?: RequirementReviewRepository;
+    /**
+     * Optional: the requirements-review feature's service, present when the reviewer is
+     * wired. Drives the special `requirements-review` gate step (run reviewer inline, the
+     * iterative answer → incorporate → re-review loop). Absent → the gate step passes
+     * through so pipelines run unchanged without the feature.
+     */
+    requirementReviewService?: RequirementReviewService;
+    /**
+     * Optional: persistence for the clarity-review (bug-report triage) feature. Read here
+     * to substitute a converged clarified report as the downstream agent context (the
+     * mirror of `requirementReviewRepository`). Absent → no substitution.
+     */
+    clarityReviewRepository?: ClarityReviewRepository;
+    /**
+     * Optional: the clarity-review feature's service, present when the reviewer is wired.
+     * Drives the special `clarity-review` gate step (inline reviewer + the iterative
+     * answer → incorporate → re-review loop). Absent → the gate step passes through.
+     */
+    clarityReviewService?: ClarityReviewService;
+    /**
+     * Optional: when the individual-usage subscription store is configured, a finished
+     * run's per-run credential activation is deleted here the moment it reaches a terminal
+     * state, bounding standing exposure to the run's own lifetime (the TTL sweep is the
+     * backstop). Absent → activations are reclaimed by the TTL sweep alone.
+     */
+    subscriptionActivationRepository?: SubscriptionActivationRepository;
+    /**
+     * Optional: resolve a workspace's per-agent-kind default model id (the same resolver
+     * the container executor uses for dispatch). The personal-credential gate consults it
+     * so a run whose block has NO pinned model but whose workspace default resolves to an
+     * individual-usage vendor is still gated up-front — matching what dispatch will resolve,
+     * instead of starting and then failing on a missing activation. Absent → the gate sees
+     * only the block's pinned model (env-routing defaults are operator-level and not gated).
+     */
+    resolveWorkspaceModelDefault?: (workspaceId: string, agentKind: string) => Promise<string | undefined>;
+    /**
+     * Optional: resolve the provider capabilities (configured direct keys +
+     * subscription vendors + whether Cloudflare AI is enabled) for a workspace and the
+     * run initiator. The start guard uses it to block a pipeline whose steps' canonical
+     * models have no usable provider. Absent → the guard is skipped (tests / unconfigured
+     * facades), exactly like the existing optional engine deps.
+     */
+    resolveProviderCapabilities?: (workspaceId: string, initiatedBy?: string | null) => Promise<ProviderCapabilities>;
+    /**
+     * Optional: when the environment integration is configured, a `deployer` step
+     * provisions an ephemeral environment deterministically through this service
+     * (no LLM), and downstream steps discover the resulting env via it.
+     */
+    environmentProvisioning?: EnvironmentProvisioningService;
+    /**
+     * Optional: when the board-scan module is configured, a `blueprints` step's
+     * decomposition tree is reconciled onto the board through this (BoardScanService).
+     * Absent → a blueprint step still runs and commits its in-repo files, but the
+     * board isn't auto-updated from it.
+     */
+    blueprintReconciler?: BlueprintReconciler;
+    /**
+     * Optional: raises human-actionable notifications (a PR needs a merge decision,
+     * a no-merger pipeline finished, CI fixing gave up). Absent → those events still
+     * transition the block but no notification surfaces (tests).
+     */
+    notificationService?: NotificationService;
+    /**
+     * Optional: resolves a workspace's runtime settings so {@link ExecutionService.start}
+     * can enforce the per-service running-task limit. Absent → the limit is never enforced
+     * (tests / unconfigured facades start runs unbounded).
+     */
+    workspaceSettingsService?: WorkspaceSettingsService;
+    /**
+     * Optional: reads a block's CI check runs so the `ci` step can gate the PR on
+     * green CI. Absent → the `ci` step is a pass-through (nothing to gate), so the
+     * engine works unchanged when GitHub CI isn't wired.
+     */
+    ciStatusProvider?: CiStatusProvider;
+    /**
+     * Optional: reads a block's PR mergeability so the `conflicts` step can gate the
+     * PR on being mergeable. Absent → the `conflicts` step is a pass-through (nothing
+     * to gate), so the engine works unchanged when GitHub isn't wired.
+     */
+    mergeabilityProvider?: PullRequestMergeabilityProvider;
+    /**
+     * Optional: reads a deployed release's Datadog monitors/SLOs so the
+     * `post-release-health` step can gate on the release looking healthy after deploy.
+     * Absent → the step is a pass-through (nothing to watch), so the engine works
+     * unchanged when Datadog isn't wired.
+     */
+    releaseHealthProvider?: ReleaseHealthProvider;
+    /**
+     * Optional: annotates an incident PagerDuty / incident.io already opened from the
+     * same monitors/SLOs with the on-call agent's investigation. Best-effort enrichment,
+     * NOT alerting (those systems already paged). Absent → no enrichment.
+     */
+    incidentEnrichment?: IncidentEnrichmentProvider;
+    /**
+     * Optional: performs the real GitHub merge when a task should become `done`.
+     * Absent → `done` is a board-only flip (tests); when wired, `done` provably
+     * means the PR was merged on the remote.
+     */
+    pullRequestMerger?: PullRequestMerger;
+    /**
+     * Optional: resolves a task's merge threshold preset (auto-merge ceilings + the
+     * CI-fixer attempt budget). Absent → the built-in {@link DEFAULT_MERGE_PRESET}.
+     */
+    mergePresetRepository?: MergePresetRepository;
+    /**
+     * Optional: files a GitHub issue / Jira ticket for the `tracker` step (the
+     * tech-debt recurring pipeline). Absent → the `tracker` step passes through
+     * without filing anything, so the engine works unchanged when no tracker is wired.
+     */
+    ticketTrackerProvider?: TicketTrackerProvider;
+    /**
+     * Optional: the LLM observability sink. When wired, each emit rolls the per-run
+     * model-call aggregates onto the matching pipeline steps (`step.metrics`) so the
+     * board shows tokens / output-limit headroom / transport-vs-execution latency
+     * live. Absent (tests / unconfigured) → steps carry no `metrics`.
+     */
+    llmObservability?: LlmObservabilityService;
+    /**
+     * Optional: whether the runtime can run the Tester's LOCAL docker-compose infra via
+     * Docker-in-Docker. Defaults to `true` (Cloudflare, Node, tests). The local facade
+     * sets it `false` for runtimes without nesting (Apple `container`), which makes
+     * {@link ExecutionService.assertTesterInfraConfigured} refuse a local-infra Tester run
+     * (steering it to the ephemeral environment or a no-infra service) instead of
+     * dispatching a job that can't stand its dependencies up.
+     */
+    localTestInfraSupported?: boolean;
+}
+/** Reconciles a Blueprinter step's tree onto the board in place (BoardScanService). */
+export interface BlueprintReconciler {
+    reconcileBlueprint(workspaceId: string, frameId: string | null, service: BlueprintService): Promise<unknown>;
+}
+/**
+ * The execution engine. It orchestrates a pipeline of agent-performed steps and
+ * is fully deterministic: `advanceInstance` moves one run forward by exactly one
+ * step, delegating the actual work — and the choice of whether to pause for a
+ * human decision — to the injected {@link AgentExecutor}. The durable workflow
+ * driver calls it in a loop. All LLM behaviour lives behind that port, so the
+ * engine here can be tested with a
+ * deterministic fake and no timing/delays.
+ */
+export declare class ExecutionService {
+    private readonly workspaceRepository;
+    private readonly blockRepository;
+    private readonly pipelineRepository;
+    private readonly executionRepository;
+    private readonly accountRepository;
+    private readonly idGenerator;
+    private readonly clock;
+    private readonly agentExecutor;
+    private readonly workRunner;
+    private readonly events;
+    private readonly board;
+    private readonly spend;
+    private readonly requirementReviewService?;
+    private readonly clarityReviewService?;
+    private readonly environmentProvisioning?;
+    /** Assembles the per-step agent context (requirements, docs, env, service frame, fragments). */
+    private readonly contextBuilder;
+    /** Resolves a `merger` step's assessment into an auto-merge or a `merge_review` notification. */
+    private readonly mergeResolver;
+    /** Drives a companion (reviewer/spec/architect) step: grade → pass / loop producer / park. */
+    private readonly companionController;
+    /** Drives the Tester gate's fix loop: report → greenlight / dispatch fixer / fail. */
+    private readonly testerController;
+    /** Drives both iterative review gates (requirements + clarity); kind-parameterised. */
+    private readonly reviewGate;
+    /** The requirements subject for {@link reviewGate}. */
+    private readonly requirementsKind;
+    /** The clarity (bug-report triage) subject for {@link reviewGate}. */
+    private readonly clarityKind;
+    private readonly blueprintReconciler?;
+    private readonly notificationService?;
+    private readonly workspaceSettingsService?;
+    private readonly llmObservability?;
+    private readonly ciStatusProvider?;
+    private readonly mergeabilityProvider?;
+    private readonly releaseHealthProvider?;
+    private readonly incidentEnrichment?;
+    private readonly prMerger?;
+    private readonly mergePresetRepository?;
+    private readonly ticketTrackerProvider?;
+    private readonly subscriptionActivations?;
+    private readonly resolveProviderCapabilities?;
+    private readonly resolveWorkspaceModelDefault?;
+    /** Whether the runtime can run the Tester's local DinD infra (false = limited mode). */
+    private readonly localTestInfraSupported;
+    /** Lazily-built polling-gate registry, keyed by `agentKind`. See {@link gateFor}. */
+    private gateRegistryCache?;
+    /**
+     * Lazily-built post-completion resolver registry, keyed by `agentKind`. See
+     * {@link stepResolverFor} and {@link StepCompletionResolver}.
+     */
+    private stepResolverCache?;
+    constructor({ workspaceRepository, blockRepository, pipelineRepository, executionRepository, accountRepository, idGenerator, clock, agentExecutor, workRunner, executionEventPublisher, boardService, spendService, documentRepository, taskRepository, requirementReviewRepository, requirementReviewService, clarityReviewRepository, clarityReviewService, environmentProvisioning, blueprintReconciler, notificationService, workspaceSettingsService, llmObservability, ciStatusProvider, mergeabilityProvider, releaseHealthProvider, incidentEnrichment, pullRequestMerger, mergePresetRepository, ticketTrackerProvider, subscriptionActivationRepository, resolveWorkspaceModelDefault, resolveProviderCapabilities, localTestInfraSupported, }: ExecutionServiceDependencies);
+    private requireWorkspace;
+    private requireBlock;
+    /**
+     * The individual-usage subscription vendors a run STARTED against `blockId` with
+     * `pipelineId` will lease a personal credential for — so the controller can gate the
+     * run on the initiator's personal subscription(s) up-front. Mirrors the dispatch-time
+     * model precedence (block pin → workspace per-kind default) across every step, AND the
+     * per-user dispatch decision: `hasPersonalSubscription(vendor)` reports whether the
+     * initiator has their own subscription for a vendor, so a dual-mode model (GLM) only
+     * gates a subscriber (a non-subscriber runs it on the Cloudflare base, ungated).
+     * Defaults to "no personal subscription" for system/unauthenticated callers.
+     */
+    individualVendorsForBlock(workspaceId: string, blockId: string, pipelineId: string, hasPersonalSubscription?: HasPersonalSubscription): Promise<SubscriptionVendor[]>;
+    /** The individual-usage vendors a failed run's resumed steps use (for the retry gate). */
+    individualVendorsForRun(workspaceId: string, executionId: string, hasPersonalSubscription?: HasPersonalSubscription): Promise<SubscriptionVendor[]>;
+    /**
+     * The set of individual-usage vendors the given steps resolve to, used to gate a run
+     * on the initiator's personal subscription(s) up-front. Delegates to the pure
+     * {@link resolveIndividualVendors}, which mirrors the dispatch-time precedence: a
+     * resolvable block pin decides the set alone (NONE for a non-subscription model), and
+     * only an unpinned run falls to the workspace per-kind defaults.
+     */
+    private resolveIndividualVendors;
+    /**
+     * Guard a Tester pipeline's start: local-mode testing must have its infra
+     * configured on the service frame — either a docker-compose path to stand the
+     * dependencies up, or the explicit "no infra dependencies" flag. Ephemeral-mode
+     * testing uses the provisioned environment, so it needs neither. Throws a
+     * {@link ConflictError} (surfaced as an actionable message) when neither is set.
+     */
+    private assertTesterInfraConfigured;
+    /**
+     * Guard a pipeline's start on having a usable provider for every step's canonical
+     * model. The model a step runs is resolved by the same precedence the dispatch path
+     * uses (block pin → workspace per-kind default); each canonical id must have a usable
+     * provider given what's configured — a direct API key for its provider, a connected
+     * subscription vendor, or the opt-in Cloudflare lib enabled. Env-routing defaults (the
+     * last fallback, with no catalog id) are operator-level and not gated, matching the
+     * personal-credential gate. A throw aborts the start cleanly before any side effects.
+     * Skipped when no capability resolver is wired (tests / unconfigured facades).
+     */
+    private assertProvidersConfiguredForPipeline;
+    /** Start a pipeline against a block, replacing any prior run on it. */
+    start(workspaceId: string, blockId: string, pipelineId: string, 
+    /**
+     * Internal user id of the initiator. Recorded on the run so an individual-usage
+     * model (Claude) uses this user's OWN personal subscription. Absent for
+     * system-initiated runs (recurring schedules) and auth-disabled dev.
+     */
+    initiatedBy?: string | null, 
+    /**
+     * Mint the per-run personal-credential activation for an individual-usage model.
+     * Invoked with the new run's id BEFORE it is persisted/dispatched, so the async
+     * steps can lease it; a throw (wrong/missing password) aborts the start cleanly
+     * with nothing persisted. The server layer supplies this (the personal store lives
+     * outside the domain Core); absent for non-individual runs.
+     */
+    activate?: (executionId: string) => Promise<void>): Promise<ExecutionInstance>;
+    /**
+     * Enforce the workspace's per-service running-task limit before a task run starts.
+     * No-ops unless the settings module is wired, the block is a task, and a limit mode
+     * is active. Counts the tasks under the same service frame that already have a live
+     * run (running / blocked / paused) — bucketed by task type when the mode is
+     * `per_type`, else shared across all types — and throws a {@link ConflictError} (→ 409,
+     * shown as a toast) when the cap is reached. The starting block is excluded from the
+     * count (its prior run is about to be replaced).
+     */
+    private assertWithinTaskLimit;
+    /**
+     * Advance a single run by exactly one step and report what happened. This is
+     * the durable driver's entry point: it reloads the run from storage (so it is
+     * safe under replay/retry), no-ops unless the run is actively running, and
+     * otherwise performs one agent step via the shared {@link stepInstance} logic.
+     */
+    advanceInstance(workspaceId: string, executionId: string, options?: AdvanceOptions): Promise<AdvanceResult>;
+    /** Advance a single running instance by one step, persisting the result. */
+    private stepInstance;
+    /**
+     * Preview the model a step will run (`provider:model`) ahead of the work, so the
+     * board can show it during the inline query / container cold-boot rather than only
+     * once the result or job handle lands. Best-effort: the executor may not implement
+     * a preview, and a resolution failure (e.g. an unwired container kind that fails at
+     * dispatch anyway) must never break the run — both yield undefined.
+     */
+    private previewStepModel;
+    /**
+     * Whether the current step will run on a flat-rate subscription (quota) model, so
+     * the spend gate can let it proceed even when the monetary budget is exhausted.
+     * Resolved through the executor (the authority on the "subscriptions always win"
+     * routing) off a full step context. Best-effort and side-effect-free: an executor
+     * without the capability, a missing block, or any resolution error all report false
+     * (the step is treated as budget-metered, the prior behaviour). Only consulted on
+     * the over-budget path, so the extra context build never touches the happy path.
+     */
+    private currentStepIsQuotaBased;
+    /**
+     * Poll the asynchronous job a parked step dispatched. Returns `awaiting_job`
+     * while it runs (the driver keeps polling), records the result and advances on
+     * success, or reports `job_failed` so the driver can fail the run. Reading run
+     * state from storage on every call keeps it safe under Workflows replay/retry:
+     * once a job's result is recorded the step's `jobId` is cleared, so a re-poll
+     * simply lets the driver advance the now-current step.
+     */
+    pollAgentJob(workspaceId: string, executionId: string): Promise<AdvanceResult>;
+    /**
+     * Re-run a polling gate step's precheck from the durable driver's `awaiting_gate`
+     * loop: which gate (ci / conflicts) is resolved from the current step's `agentKind`,
+     * and it returns the same outcomes as the initial evaluation (precheck passes →
+     * advance, still computing → keep polling, fails → dispatch a helper or give up).
+     * Safe under replay: reads run state fresh each call. A no-op unless the current
+     * step is a gate actively in its `checking` phase.
+     */
+    pollGate(workspaceId: string, executionId: string): Promise<AdvanceResult>;
+    /**
+     * Decide what happens when the durable driver's GATE poll budget (ciMaxPolls ×
+     * ciPollInterval) is spent while a gate is still `pending` — called by both runtime
+     * drivers (Cloudflare ExecutionWorkflow / Node `driveExecution`) instead of failing
+     * the run directly, so the per-gate policy lives in one place. Most gates `fail`
+     * (CI never went green / the PR never became mergeable). A time-windowed watch gate
+     * (post-release-health, `pollExhaustion: 'pass'`) instead PASSES: the watch window
+     * simply outlasted the poll budget with no regression observed, which is healthy — not
+     * a timeout. Returns the result the driver should act on (it never re-fails for a fail
+     * gate; it returns a `job_failed` the driver funnels through its single `failRun`).
+     */
+    resolveGatePollExhaustion(workspaceId: string, executionId: string): Promise<AdvanceResult>;
+    /**
+     * Transition a step into `working`, stamping its start time the first time it
+     * actually begins. Set-once so a Workflows replay (which re-runs `advance`)
+     * preserves the original start rather than resetting it on every replay. An
+     * explicit re-run clears `startedAt` first (see {@link requestStepChanges}) so
+     * the fresh attempt is timed from scratch.
+     */
+    private startStep;
+    /**
+     * 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.
+     */
+    private finishStep;
+    /**
+     * Finish a gated step that was skipped (its estimate gate was not satisfied) and either
+     * complete the run or advance to the next step — the deterministic finish/advance tail
+     * of {@link recordStepResult}, minus all the agent-result handling (no LLM ran, so there
+     * is no usage / decision / PR / artifact / approval / resolver to process). The step is
+     * marked `skipped` with empty output so the UI renders "skipped (gated)".
+     */
+    private skipGatedStep;
+    /**
+     * 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}).
+     */
+    private pauseStepForInput;
+    /**
+     * Record a completed agent step's result and report what the driver should do
+     * next: meter token usage, park on a raised decision, or persist the output
+     * (and any opened PR) and either finish the run or advance to the next step.
+     * Shared by the inline path and the async-job poll path.
+     */
+    private recordStepResult;
+    /**
+     * 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
+     * finished or evicted job), its timings, approval gate, live subtasks and last
+     * output, and drop it back to `pending`. Preserves the step's identity
+     * (`agentKind` / `requiresApproval`) and any companion budget/verdict history.
+     */
+    private resetStepForRerun;
+    /**
+     * 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.
+     */
+    private rerunProducerThrough;
+    /**
+     * 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.
+     */
+    private companionProducerIndex;
+    /**
+     * 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 ({@link evaluateCompanion}) and the human-granted extra round
+     * ({@link resolveCompanionExceeded}), so both consume the budget identically.
+     */
+    private loopCompanionProducer;
+    /**
+     * Deterministically provision an ephemeral environment for a deployer step.
+     * Produces a human-readable summary as the step output and reports no token
+     * usage (it incurs no LLM cost). Errors are swallowed into the output unless
+     * the durable driver wants them surfaced for its per-step retry.
+     */
+    private runDeployer;
+    /**
+     * File a tracking issue/ticket for a `tracker` step from the preceding `analysis`
+     * output. Non-LLM and best-effort: when no provider is wired or none is configured
+     * for the workspace it simply notes the skip; a filing error is folded into the
+     * step output rather than failing the run (the implementation still proceeds).
+     */
+    private runTracker;
+    /**
+     * The polling-gate registry, keyed by `agentKind`. A gate runs a programmatic
+     * precheck against a provider and only escalates to a helper container agent on a
+     * negative verdict. Built lazily (the closures capture `this`, so the providers /
+     * merge preset / notification helpers resolve at call time). Returns undefined for a
+     * non-gate kind. See {@link GateDefinition} and {@link evaluateGate}.
+     */
+    private gateFor;
+    /**
+     * The post-completion resolver for an agent kind, or undefined when the kind has none.
+     * A resolver runs DETERMINISTIC backend follow-up once the step's agent finishes — e.g.
+     * the merger performs the real GitHub merge — independent of the step's position in the
+     * pipeline. Built lazily (closures capture `this`). See {@link StepCompletionResolver}.
+     */
+    private stepResolverFor;
+    private buildStepResolverRegistry;
+    private buildGateRegistry;
+    /**
+     * Evaluate a polling gate step once and decide (shared by the initial advance and the
+     * durable `awaiting_gate` re-poll):
+     *   - no provider wired → pass-through (advance; nothing to gate);
+     *   - precheck passes   → advance to the next step (the helper agent is NEVER spun up);
+     *   - still computing   → `awaiting_gate` (the driver sleeps then calls {@link pollGate});
+     *   - fails, budget left → dispatch the helper container agent (`awaiting_job`);
+     *   - fails, budget spent → the gate's exhaustion handler, then fail the run.
+     */
+    private evaluateGate;
+    /**
+     * Dispatch a gate's helper container agent on a failed precheck: build the agent
+     * context with the kind overridden to the helper (it clones the PR head branch and
+     * pushes — no new PR), park on the job, and flip the gate to `working`. Idempotent
+     * under replay via the step's `jobId` (re-attach handled in {@link evaluateGate}).
+     */
+    private dispatchGateHelper;
+    /**
+     * Raise a `decision_required` notification when a run parks on an iteration-cap gate
+     * after spending its automatic budget — a quality companion at its rework cap or an
+     * iterative reviewer (requirements / clarity) at its iteration cap. Without it the
+     * three-choice decision is reachable only by drilling into the parked step, so the run
+     * looks silently stuck. Best-effort: a missing notification service (tests) or block is
+     * a no-op.
+     */
+    private raiseDecisionRequired;
+    /**
+     * 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.
+     */
+    private ensureWaitingNotification;
+    /**
+     * 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.
+     */
+    private clearWaitingNotification;
+    /** Raise a `ci_failed` notification when the CI gate exhausts its fixer budget. */
+    private raiseCiFailed;
+    /** Provision inputs (`{{input.*}}`) derived from the block under deployment. */
+    private deployInputs;
+    /**
+     * Typed git/PR/repo context for the deployer, derived from the block's PR ref. A
+     * PR-environment provider (e.g. an in-house adapter) needs the branch/repo to target
+     * the right environment; the same values are also flattened into `{{input.*}}` for
+     * the manifest path. `owner`/`repo` are parsed from the PR url when present.
+     */
+    private deployContext;
+    /**
+     * Invoke the agent for an already-built context. Failures are swallowed into the
+     * step output so a run never wedges — unless `rethrowAgentErrors` is set (the
+     * durable path), in which case the error propagates so the driver's per-step
+     * retry can take over.
+     */
+    private runAgent;
+    /**
+     * Strictly parse a Blueprinter step's tree and reconcile it onto the board. The
+     * blueprint maps the whole repository, so it is reconciled onto the run block's
+     * **service frame** (walked up from the block), not the task the run targeted.
+     * Best-effort and reconciler-gated: a parse/reconcile failure is logged-by-throw
+     * upstream only when the reconciler is wired; with no reconciler it is a no-op so
+     * the blueprint's in-repo files still land.
+     */
+    private ingestBlueprint;
+    /**
+     * Strictly validate a spec-writer step's unified specification. The canonical record
+     * is the in-repo `spec/` files the harness already committed; this is the trust
+     * boundary (a malformed payload is dropped, never trusted) plus a client refresh
+     * nudge. A persisted board projection is a deliberate later phase.
+     */
+    private ingestSpec;
+    /**
+     * Park a step on the durable decision-wait the approval gate uses, so a human (or the
+     * dedicated review window) can drive an iterative loop and resume the run. Shared by the
+     * requirements gate and the companion iteration-cap gate: both reuse the SAME parking
+     * mechanism rather than each rolling its own. `proposal` seeds the gate's stored text
+     * (the companion's latest feedback; empty for the requirements window, which renders its
+     * own structured surface via the universal result-view registry).
+     */
+    private parkStepOnDecision;
+    /**
+     * Two gates park on a `step.approval` but are NOT generic prose approvals — they are
+     * iterative gates driven by their own dedicated surface, never the generic
+     * approve/request-changes/reject resolvers (which would advance the run bypassing the
+     * loop). Guard those resolvers so a stray approve can't short-circuit either gate:
+     * - the requirements-review gate (driven by re-review / proceed / resolve-exceeded);
+     * - a companion gate that hit its rework cap (`companion.exceeded`), driven by
+     *   {@link resolveCompanionExceeded}'s one-more-round / proceed / stop-reset choices.
+     */
+    private assertNotIterativeGate;
+    /**
+     * The requirements subject for {@link reviewGate}: closures over the requirements reviewer
+     * service. The service-not-configured guard preserves the exact 409 the inline reviewer
+     * raised before this extraction.
+     */
+    private buildRequirementsKind;
+    /**
+     * The clarity (bug-report triage) subject for {@link reviewGate}: threads any upstream
+     * `bug-investigator` output into the reviewer/incorporation context, otherwise identical to
+     * the requirements kind.
+     */
+    private buildClarityKind;
+    /**
+     * Run a fresh reviewer pass over a block's collected requirements, snapshotting the
+     * task's merge-preset knobs (iteration budget + tolerated severity) onto the review.
+     * Shared by the pipeline gate and the off-path inspector "Run review" surface, so both
+     * honour the task's preset identically.
+     */
+    reviewRequirements(workspaceId: string, blockId: string): Promise<RequirementReview>;
+    /**
+     * Incorporate the human's settled answers ASYNCHRONOUSLY. Validates that every finding is
+     * answered/dismissed, flags the review `incorporating`, records the intent on the parked
+     * gate step, and signals the durable driver to wake — which folds the answers and
+     * re-reviews in the background. Off-path (no parked run) the fold + re-review run inline.
+     */
+    incorporateRequirements(workspaceId: string, blockId: string, feedback?: string): Promise<RequirementReview>;
+    /**
+     * Re-review the incorporated document (one more reviewer pass). On convergence
+     * (`incorporated`) the parked run advances; otherwise the window shows the next cycle
+     * (`ready`) or the iteration-cap choices (`exceeded`).
+     */
+    reReviewRequirements(workspaceId: string, blockId: string): Promise<RequirementReview>;
+    /**
+     * Proceed: settle the requirements (the last incorporated doc, if any, becomes what
+     * downstream agents consume) and advance the parked run.
+     */
+    proceedRequirements(workspaceId: string, blockId: string): Promise<RequirementReview>;
+    /**
+     * Route an iteration-cap resolution to its gate-specific handlers. `stop-reset` is
+     * uniform across gates: cancel the run and return the block to phase zero (editable),
+     * keeping whatever reference artifact each gate persists (the requirements doc on its
+     * own table; a companion's producer output on its branch). Shared by the requirements
+     * gate ({@link resolveRequirementsExceeded}) and the companion gate
+     * ({@link resolveCompanionExceeded}) so the three-way choice lives in one place.
+     */
+    private dispatchIterationCap;
+    /**
+     * Resolve a requirements review that hit its iteration cap: grant one more round,
+     * proceed with the last incorporated doc, or stop the task and reset it to phase zero.
+     */
+    resolveRequirementsExceeded(workspaceId: string, blockId: string, choice: ResolveRequirementsExceededChoice): Promise<RequirementReview>;
+    /**
+     * Resolve a companion step parked at its automatic-rework cap (`companion.exceeded`):
+     * grant one more round, proceed accepting the producer's current output, or stop the
+     * task and reset it to phase zero. The companion mirror of
+     * {@link resolveRequirementsExceeded}, sharing the iteration-cap dispatch + the
+     * gate-resume plumbing. Idempotent — an already-resolved gate returns the instance
+     * unchanged. Scoped by execution + approval id (the execution controller surface),
+     * since a companion gate is not block-addressed like the requirements window.
+     */
+    resolveCompanionExceeded(workspaceId: string, executionId: string, approvalId: string, choice: IterationCapChoice): Promise<ExecutionInstance>;
+    /**
+     * Finish a gate step the human just resolved (its `approval` already marked `approved`),
+     * then either finish the run (final step) or advance to the next step, persist, and wake
+     * the parked durable driver. The single advance/finalize/signal path shared by every
+     * gate-resume site — the generic approval ({@link approveStep}), the review gates (via
+     * {@link ReviewGateController}) and the companion iteration-cap proceed
+     * ({@link resolveCompanionExceeded}) — so the logic lives in exactly one place.
+     */
+    private advancePastResolvedGate;
+    /** The latest `bug-investigator` step output on a run (the triage subject), or undefined. */
+    private investigationFor;
+    /** Resolve a block's investigator output via its current execution (off the gate path). */
+    private investigationForBlock;
+    /**
+     * Run a fresh clarity reviewer pass over a block's bug report, snapshotting the task's
+     * merge-preset knobs (iteration budget + tolerated severity) and threading in any
+     * `bug-investigator` output as the triage subject. Shared by the gate + the off-path
+     * inspector "Run review" surface.
+     */
+    reviewClarity(workspaceId: string, blockId: string): Promise<ClarityReview>;
+    /** Incorporate the human's settled answers ASYNCHRONOUSLY (the clarity mirror of {@link incorporateRequirements}). */
+    incorporateClarity(workspaceId: string, blockId: string, feedback?: string): Promise<ClarityReview>;
+    /** Re-review the clarified report (one more pass). On convergence the parked run advances. */
+    reReviewClarity(workspaceId: string, blockId: string): Promise<ClarityReview>;
+    /** Proceed: settle the clarity review and advance the parked run. */
+    proceedClarity(workspaceId: string, blockId: string): Promise<ClarityReview>;
+    /** Resolve a clarity review that hit its iteration cap (extra-round / proceed / stop-reset). */
+    resolveClarityExceeded(workspaceId: string, blockId: string, choice: ResolveRequirementsExceededChoice): Promise<ClarityReview>;
+    /**
+     * Push the run's latest state to subscribed clients, alongside its rolled-up
+     * block so the board updates without a refetch. Best-effort: the publisher
+     * swallows its own errors, and the persisted run remains the source of truth.
+     */
+    private emitInstance;
+    /**
+     * 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.
+     */
+    private attachStepMetrics;
+    /** Set the block's in-progress/blocked status and step-completion progress. */
+    private updateBlockProgress;
+    /**
+     * 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.
+     */
+    private refreshBlockProgress;
+    /**
+     * 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 {@link 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 {@link finalizeMerge}).
+     */
+    private finalizeBlock;
+    /**
+     * Merge a block's PR for real, then mark it `done`. The remote merge happens
+     * FIRST (via the {@link PullRequestMerger} port) and only on its success does the
+     * block flip to `done` — so `done` provably means "merged", not a board-only
+     * status. When no merger is wired (tests) this degrades to the old board-only
+     * flip. Throws if the remote merge fails so callers can fall back to a manual
+     * merge / review notification.
+     */
+    private finalizeMerge;
+    /**
+     * Resolve the merge threshold preset that governs a task: its explicitly-picked
+     * preset, else the workspace default, else the built-in {@link DEFAULT_MERGE_PRESET}.
+     * Returns just the thresholds the engine compares against (+ the CI attempt budget).
+     */
+    private resolveMergePreset;
+    /**
+     * Resolve a finished `on-call` investigation (the post-release-health gate's helper):
+     * parse its assessment, raise a `release_regression` notification for a human, enrich
+     * any incident PagerDuty/incident.io already opened, then finish the gate step so the
+     * run completes (the human acts on the notification out-of-band — the engine never
+     * auto-reverts). Best-effort on the side-effects; the step always finishes.
+     */
+    private resolveOnCallStep;
+    /** Raise a `release_regression` notification carrying the on-call assessment + signals. */
+    private raiseReleaseRegression;
+    /**
+     * Best-effort: annotate an incident PagerDuty / incident.io already opened (from the
+     * same monitors/SLOs) with the on-call investigation. NOT alerting — those systems
+     * already paged. A no-op when no provider is wired or no matching incident exists.
+     */
+    private enrichIncident;
+    /** Raise a `pipeline_complete` notification for a no-merger run awaiting confirmation. */
+    private raisePipelineComplete;
+    /**
+     * Implementing a task assigned to a module materialises that module: create it
+     * in the service if missing, then move the task inside it.
+     */
+    private applyModuleAssignment;
+    /** Resolve a pending decision; the run's next step lets the agent finish it. */
+    resolveDecision(workspaceId: string, executionId: string, decisionId: string, choice: string): Promise<ExecutionInstance>;
+    /**
+     * Approve a step's gated proposal: the run advances to the next step, carrying
+     * the (optionally human-edited) proposal forward as context. Mirrors
+     * {@link resolveDecision}'s durable-wake but *advances* the pipeline instead of
+     * re-running the step (the step is already done). Idempotent — re-approving an
+     * already-approved gate is a no-op.
+     */
+    approveStep(workspaceId: string, executionId: string, approvalId: string, opts?: {
+        proposal?: string;
+    }): Promise<ExecutionInstance>;
+    /**
+     * Request changes on a step's gated proposal: the same step re-runs with the
+     * human's freeform feedback and/or per-block comments (and its prior proposal)
+     * folded into the agent's context (see {@link AgentContextBuilder}). The run is left
+     * `running` on the same step; on the re-run's completion the gate is raised
+     * afresh. At least one of `feedback`/`comments` is expected (the controller
+     * validates this), but an empty review is harmless — the agent simply re-runs.
+     */
+    requestStepChanges(workspaceId: string, executionId: string, approvalId: string, review: {
+        feedback?: string;
+        comments?: StepReviewComment[];
+    }): Promise<ExecutionInstance>;
+    /**
+     * Reject a step's gated proposal: the run stops entirely. The gate is marked
+     * `rejected` and the run is failed with a dedicated `rejected` failure kind, so
+     * the board surfaces it via the shared failure banner (block → `blocked`) with a
+     * Retry affordance. The parked durable run is woken so it observes the now-terminal
+     * status and stops (the workflow's advance loop no-ops on a non-running run).
+     * Idempotent — rejecting an already-terminal gate is a no-op.
+     */
+    rejectStep(workspaceId: string, executionId: string, approvalId: string, reason?: string): Promise<ExecutionInstance>;
+    /** Merge an open PR: a block moves from `pr_ready` to `done`. */
+    mergePr(workspaceId: string, blockId: string): Promise<Block>;
+    /**
+     * Record a terminal agent failure: persist a structured {@link AgentFailure},
+     * flip the run to `failed`, and mark the block `blocked` (needs attention) — NOT
+     * `pr_ready`, which looked like success and hid the failure. The board then
+     * renders the same failure banner + retry as a failed bootstrap. Called by the
+     * durable driver once a step has exhausted its retries (or a job/decision
+     * faulted); `kind` classifies the cause so the right hint is shown.
+     */
+    failRun(workspaceId: string, executionId: string, message: string, kind?: AgentFailureKind, detail?: string | null): Promise<void>;
+    /**
+     * Retry a failed run: re-drive the same pipeline on the same block, **resuming
+     * from the step that actually failed** rather than restarting from step 0. The
+     * steps that already completed are preserved (so a `coder` failure in `pl_full`
+     * doesn't re-run the human-gated `requirements`/`architect` steps before it);
+     * the failed step and everything after it are reset to a clean, re-runnable
+     * state. Only a `failed` run can be retried.
+     *
+     * A fresh instance id is minted because the durable runner addresses one
+     * Workflows instance per execution id and the failed one is terminal — the new
+     * instance simply starts with `currentStep` pointed at the failed step, so the
+     * driver advances forward from there and never re-issues the completed steps'
+     * work. Mirrors {@link BootstrapService.retry}; both are reached via the unified
+     * `POST /agent-runs/:id/retry` endpoint.
+     */
+    retry(workspaceId: string, executionId: string, 
+    /** The retrying user (their personal subscription is used for individual-usage
+     *  models). Falls back to the original initiator when omitted. */
+    initiatedBy?: string | null, 
+    /** Mint the per-run personal-credential activation (see {@link start}). */
+    activate?: (executionId: string) => Promise<void>): Promise<ExecutionInstance>;
+    /**
+     * Restart a run from a human-chosen step: re-run from `fromStepIndex` onward,
+     * regardless of how far the run had progressed (a `done`, `failed`, `blocked`,
+     * `paused` or still-`running` run are all valid sources). Unlike {@link retry}
+     * (which resumes at the first FAILURE) this rewinds to an arbitrary step the user
+     * picked — so it can re-run steps that already completed.
+     *
+     * What is preserved vs reset:
+     * - Steps BEFORE `fromStepIndex` keep their `output`/approval/timing untouched, so
+     *   the engine still hands the restarted step its predecessors' work as
+     *   `priorOutputs` (and their resolved `decisions`) — a useful handoff.
+     * - The chosen step and every later one are reset to a clean, re-runnable state,
+     *   dropping each step's iteration counters (companion attempts, gate/test attempts,
+     *   eviction recoveries) so the restart starts those loops from zero.
+     * - A block's incorporated requirements are NOT touched: they live on the
+     *   requirement-review record, so a restarted spec-writer/coder still receives the
+     *   incorporated document (or the base description when none was generated). When the
+     *   chosen step is the `requirements-review` gate ITSELF, re-running it mints a fresh
+     *   iteration-1 review (the reviewer's `review()` replaces the prior one), which is
+     *   exactly the "reset the iterations counter from this step" semantics.
+     *
+     * Like {@link retry} a fresh instance id is minted (the durable runner addresses one
+     * driver per execution id). Any still-live driver/container for the run being
+     * replaced is torn down first, so restarting a RUNNING run never orphans a container
+     * or a parked Workflows instance.
+     */
+    restartFromStep(workspaceId: string, executionId: string, fromStepIndex: number, 
+    /** The restarting user (their personal subscription is used for individual-usage
+     *  models). Falls back to the original initiator when omitted. */
+    initiatedBy?: string | null, 
+    /** Mint the per-run personal-credential activation (see {@link start}). */
+    activate?: (executionId: string) => Promise<void>): Promise<ExecutionInstance>;
+    /**
+     * Resume every run paused by the spend safeguard in this workspace. Flips them
+     * back to `running` and re-drives the durable runner. If the budget is still
+     * exhausted the spend gate will simply pause them again on their next step.
+     */
+    resumePaused(workspaceId: string): Promise<ExecutionInstance[]>;
+    /** Cancel the run on a block, returning it to `planned`. */
+    cancel(workspaceId: string, blockId: string): Promise<Block>;
+    /**
+     * Explicitly stop a *running* run by id (the unified `POST /agent-runs/:id/stop`
+     * surface): kill its per-run container, tear down the durable driver, then record
+     * a terminal `cancelled` failure so the board shows the run stopped (with retry)
+     * rather than spinning forever. Idempotent — a run already terminal is returned
+     * as-is. `opts.reason`/`opts.kind` let the orphan sweep reuse this with its own
+     * wording instead of the user-facing default.
+     */
+    stopRun(workspaceId: string, executionId: string, opts?: {
+        reason?: string;
+        kind?: AgentFailureKind;
+    }): Promise<ExecutionInstance>;
+    /**
+     * Tear down every run under a block subtree — kill each container, terminate each
+     * durable driver, and delete the run record — so deleting a service/module never
+     * orphans a container or a Workflows instance. Best-effort and silent: the board
+     * delete that follows emits the coarse refresh, so no per-run event is needed.
+     */
+    teardownForBlockTree(workspaceId: string, rootId: string): Promise<void>;
+    /**
+     * Best-effort: reclaim the per-run container backing an execution. The container is
+     * addressed by the run (execution) id, so a backend that shares one across the run
+     * (Cloudflare, local Docker) tears the whole thing down. A per-job backend (a
+     * self-hosted pool) has no run container, so it cancels the run's IN-FLIGHT step job
+     * instead — hence we pass the current step's job id alongside the run id. A no-op for
+     * inline executors (no `stopJob`) and for an already-gone container/job; never
+     * throws, so it can't derail the teardown that calls it.
+     */
+    private stopRunContainer;
+}
+//# sourceMappingURL=ExecutionService.d.ts.map