@cat-factory/orchestration 0.123.4 → 0.123.5

package/dist/modules/execution/ExecutionService.js

@@ -1,21 +1,23 @@
-import { allPullRequests, DEFAULT_COMPANION_MAX_ATTEMPTS, frameAllowsVisualPipeline, frameProfile, isLocalRunner, pipelineHasVisualStep, } from '@cat-factory/contracts';
-import { BINARY_STORAGE_TRAIT, bugInvestigation, companionFor, companionTargets, hasTrait, INTERVIEW_GATE_TRAIT, isCompanionKind, isInlineModelStep, } from '@cat-factory/agents';
-import { assertPipelineLaunchable, validatePipelineShape, } from '../pipelines/pipelineShape.js';
+import { allPullRequests, DEFAULT_COMPANION_MAX_ATTEMPTS, pipelineHasVisualStep, } from '@cat-factory/contracts';
+import { companionFor, companionTargets, hasTrait, INTERVIEW_GATE_TRAIT, isCompanionKind, } from '@cat-factory/agents';
+import { assertPipelineLaunchable } from '../pipelines/pipelineShape.js';
 import { shouldRunGatedStep } from './stepGating.logic.js';
 import { resolveIndividualVendors, } from './individualVendors.logic.js';
-import { assertFound, ConflictError, isAllowedByFamilyPolicy, isModelUsable, isModelUsableInline, NotFoundError, resolveModelRef, RunContendedError, subscriptionOptionFor, ValidationError, } from '@cat-factory/kernel';
+import { assertFound, ConflictError, NotFoundError, RunContendedError, ValidationError, } from '@cat-factory/kernel';
 import { DEFAULT_RISK_POLICY } from '@cat-factory/kernel';
-import { REQUIREMENTS_REVIEW_AGENT_KIND, CLARITY_REVIEW_AGENT_KIND, REQUIREMENTS_BRAINSTORM_AGENT_KIND, ARCHITECTURE_BRAINSTORM_AGENT_KIND, BUG_INVESTIGATOR_AGENT_KIND, isTesterKind, HUMAN_TEST_AGENT_KIND, VISUAL_CONFIRM_AGENT_KIND, HUMAN_REVIEW_AGENT_KIND, } from './ci.logic.js';
+import { REQUIREMENTS_REVIEW_AGENT_KIND, CLARITY_REVIEW_AGENT_KIND, REQUIREMENTS_BRAINSTORM_AGENT_KIND, ARCHITECTURE_BRAINSTORM_AGENT_KIND, isTesterKind, HUMAN_TEST_AGENT_KIND, VISUAL_CONFIRM_AGENT_KIND, HUMAN_REVIEW_AGENT_KIND, } from './ci.logic.js';
 import { DEFAULT_FOLLOW_UP_MAX_LOOPS, FOLLOW_UP_PRODUCER_KIND } from './followUp.logic.js';
 import { AgentContextBuilder, } from './AgentContextBuilder.js';
 import { CompanionController } from './CompanionController.js';
 import { StepGraph } from './StepGraph.js';
 import { RunStateMachine } from './RunStateMachine.js';
 import { RunDispatcher } from './RunDispatcher.js';
+import { RunAdmission } from './RunAdmission.js';
 import { inferTechnicalLabel } from './technical.logic.js';
 import { MergeResolver } from './MergeResolver.js';
 import { orderPrsForMerge } from './mergeOrder.logic.js';
 import { ReviewGateController } from './ReviewGateController.js';
+import { buildBrainstormKind, buildClarityKind, buildRequirementsKind } from './review-kinds.js';
 import { ForkDecisionController } from './ForkDecisionController.js';
 import { PrReviewController } from './PrReviewController.js';
 import { BrainstormActions, ClarityReviewActions, RequirementReviewActions, } from './gate-window-facades.js';
@@ -27,14 +29,10 @@ import { VisualConfirmationController } from './VisualConfirmationController.js'
 import { InitiativeInterviewController } from './InitiativeInterviewController.js';
 import { DocInterviewController } from './DocInterviewController.js';
 import { FORK_DECISION_PRODUCER_KIND } from './forkDecision.logic.js';
-import { assertInitiativeShapeAllowed, } from '../initiative/initiative.logic.js';
 import { isAsyncAgentExecutor } from '@cat-factory/kernel';
-import { dependenciesMet, descendantIds, serviceOf, unmetDependencies, } from '../board/board.logic.js';
+import { dependenciesMet, descendantIds, serviceOf } from '../board/board.logic.js';
 import { requireWorkspace } from '@cat-factory/kernel';
 import { carryForwardFailures, carryForwardOutputs, planResumedSteps, planRestartFromStep, } from './retry.logic.js';
-import { decideTesterInfra, ENV_CONSUMER_KINDS, needsDeployerBeforeConsumer, TESTER_INFRA_MESSAGES, } from './tester-infra.logic.js';
-import { decideDeployerConfig, deployerServiceConfigIssues, hasEnabledDeployerStep, } from './deployer.logic.js';
-import { hasLiveServiceBinding, hasServiceBinding } from './frontend-infra.logic.js';
 /**
  * The execution engine. It orchestrates a pipeline of agent-performed steps and
  * is fully deterministic: `advanceInstance` moves one run forward by exactly one
@@ -62,13 +60,15 @@ export class ExecutionService {
     events;
     board;
     spend;
-    requirementReviewService;
-    docInterviewService;
-    clarityReviewService;
-    brainstormServices;
-    environmentProvisioning;
     /** Assembles the per-step agent context (requirements, docs, env, service frame, fragments). */
     contextBuilder;
+    /**
+     * The run-admission preflights (the `assert*` family): every config/resource precondition
+     * a START / RETRY / RESTART must satisfy, extracted to {@link RunAdmission} so the guard
+     * family can grow without re-bloating the engine. Also owns the shared
+     * {@link RunAdmission.modelIdIsMetered} predicate the spend gates use.
+     */
+    admission;
     /** Resolves a `merger` step's assessment into an auto-merge or a `merge_review` notification. */
     mergeResolver;
     /** Drives a companion (reviewer/spec/architect) step: grade → pass / loop producer / park. */
@@ -106,8 +106,10 @@ export class ExecutionService {
     // `resolveRunRepoContext` / `runInitiatorScope` are NOT stored on the engine: their only
     // consumers (the ingest/follow-up/tracker/notification paths + the pre/post-op repo binding +
     // the initiator scope) moved to {@link RunDispatcher} (and the controllers / RunStateMachine),
-    // so the constructor forwards the destructured params straight to those collaborators.
-    workspaceSettingsService;
+    // so the constructor forwards the destructured params straight to those collaborators. The
+    // admission-only seams (`workspaceSettingsService` / `resolveProviderCapabilities` /
+    // `inlineHarnessRef` / `resolveBinaryArtifactStore` / `assertAgentBackendConfigured` /
+    // `environmentProvisioning`) likewise live on {@link RunAdmission} (and the controllers).
     prMerger;
     notifications;
     riskPolicyRepository;
@@ -115,18 +117,7 @@ export class ExecutionService {
     issueWriteback;
     subscriptionActivations;
     pokeInitiativeLoop;
-    resolveProviderCapabilities;
-    inlineHarnessRef;
     resolveWorkspaceModelDefault;
-    /** Start-time assertion that a container-agent backend is configured (local-mode pool). */
-    assertAgentBackendConfigured;
-    /**
-     * Resolves the per-account binary-artifact store, used by the start gate to refuse a
-     * pipeline carrying a {@link BINARY_STORAGE_TRAIT} kind (e.g. the UI Tester) when the
-     * account has no storage configured. Absent (tests/conformance with no store wired) ⇒
-     * the gate passes through, like the other optional start guards.
-     */
-    resolveBinaryArtifactStore;
     /**
      * The per-step dispatch + completion spine (the four registries, the completion hub, the
      * gate machinery, the deterministic deployer/tracker steps, the pre/post-op cluster, the
@@ -167,11 +158,6 @@ export class ExecutionService {
         this.events = executionEventPublisher;
         this.board = boardService;
         this.spend = spendService;
-        this.requirementReviewService = requirementReviewService;
-        this.docInterviewService = docInterviewService;
-        this.clarityReviewService = clarityReviewService;
-        this.brainstormServices = brainstormServices;
-        this.environmentProvisioning = environmentProvisioning;
         this.contextBuilder = new AgentContextBuilder({
             workspaceRepository,
             blockRepository,
@@ -191,6 +177,23 @@ export class ExecutionService {
             fragmentResolver,
             skillResolver,
         });
+        // The run-admission preflights (the shared start/retry/restart `assert*` gate family).
+        // The admission-only seams are forwarded here rather than stored on the engine.
+        this.admission = new RunAdmission({
+            workspaceRepository,
+            blockRepository,
+            executionRepository,
+            contextBuilder: this.contextBuilder,
+            agentKindRegistry,
+            spend: spendService,
+            environmentProvisioning,
+            workspaceSettingsService,
+            resolveBinaryArtifactStore,
+            resolveProviderCapabilities,
+            inlineHarnessRef,
+            resolveWorkspaceModelDefault,
+            assertAgentBackendConfigured,
+        });
         this.mergeResolver = new MergeResolver({
             blockRepository,
             notificationService,
@@ -317,10 +320,22 @@ export class ExecutionService {
             clock,
             notificationService,
         });
-        this.requirementsKind = this.buildRequirementsKind();
-        this.clarityKind = this.buildClarityKind();
-        this.requirementsBrainstormKind = this.buildBrainstormKind('requirements', REQUIREMENTS_BRAINSTORM_AGENT_KIND);
-        this.architectureBrainstormKind = this.buildBrainstormKind('architecture', ARCHITECTURE_BRAINSTORM_AGENT_KIND);
+        // The review-gate subjects (requirements / clarity / the two brainstorm stages), built by
+        // the factories in review-kinds.ts over one shared closure of collaborators — each subject's
+        // differentiators live there, not on the engine.
+        const reviewKindDeps = {
+            events: executionEventPublisher,
+            blockRepository,
+            executionRepository,
+            requirementReviewService,
+            clarityReviewService,
+            brainstormServices,
+            issueWriteback,
+        };
+        this.requirementsKind = buildRequirementsKind(reviewKindDeps);
+        this.clarityKind = buildClarityKind(reviewKindDeps);
+        this.requirementsBrainstormKind = buildBrainstormKind('requirements', REQUIREMENTS_BRAINSTORM_AGENT_KIND, reviewKindDeps);
+        this.architectureBrainstormKind = buildBrainstormKind('architecture', ARCHITECTURE_BRAINSTORM_AGENT_KIND, reviewKindDeps);
         // The interactive-planning interviewer gate — wired whenever the initiative store is
         // present (the entity is where its state lives). The interviewer LLM is optional: without
         // it (or without a model) the gate passes through, so planning still runs off the raw
@@ -399,7 +414,7 @@ export class ExecutionService {
             resolveRunRepoContext,
             resolveProviderCapabilities,
             resolveRiskPolicy: (ws, block) => this.resolveRiskPolicy(ws, block),
-            modelIdIsMetered: (id, caps) => this.modelIdIsMetered(id, caps),
+            modelIdIsMetered: (id, caps) => this.admission.modelIdIsMetered(id, caps),
         });
         // Group the per-feature gate-window actions into cohesive sub-facades (exposed as
         // getters below) so they stop bloating the engine's public surface as ~30 near-identical
@@ -407,7 +422,6 @@ export class ExecutionService {
         this.requirementsReviewActions = new RequirementReviewActions(this.reviewGate, this.requirementsKind);
         this.clarityReviewActions = new ClarityReviewActions(this.reviewGate, this.clarityKind);
         this.brainstormActions = new BrainstormActions(this.reviewGate, (stage) => this.brainstormKindFor(stage));
-        this.workspaceSettingsService = workspaceSettingsService;
         this.prMerger = pullRequestMerger;
         this.notifications = notificationService;
         this.riskPolicyRepository = riskPolicyRepository;
@@ -416,10 +430,6 @@ export class ExecutionService {
         this.subscriptionActivations = subscriptionActivationRepository;
         this.pokeInitiativeLoop = pokeInitiativeLoop;
         this.resolveWorkspaceModelDefault = resolveWorkspaceModelDefault;
-        this.resolveProviderCapabilities = resolveProviderCapabilities;
-        this.inlineHarnessRef = inlineHarnessRef;
-        this.assertAgentBackendConfigured = assertAgentBackendConfigured;
-        this.resolveBinaryArtifactStore = resolveBinaryArtifactStore;
     }
     // ---- gate-window action sub-facades -------------------------------------
     // Per-feature groupings of the dedicated review/test window actions, consumed by the
@@ -503,428 +513,6 @@ export class ExecutionService {
         const resolveDefault = this.resolveWorkspaceModelDefault;
         return resolveIndividualVendors(blockModelId, agentKinds, resolveDefault ? (kind) => resolveDefault(workspaceId, kind, modelPresetId) : undefined, hasPersonalSubscription);
     }
-    /**
-     * Guard a run start when the pipeline carries a VISUAL step (`tester-ui` /
-     * `visual-confirmation`): such a step exercises a rendered UI, so it only makes sense where
-     * there is a UI to drive — a `type: 'frontend'` frame (it owns the app under test) or a frame
-     * a `frontend` frame links to (the linked frontend is the UI a change to that service is
-     * validated through). On any other frame (a service with no linked frontend, a `library` /
-     * `document` repo) a `tester-ui` step would have nothing to drive, so refuse the start with an
-     * actionable {@link ConflictError} (`visual_pipeline_no_frontend`). The frontend surfaces the
-     * SAME rule (via the shared `frameAllowsVisualPipeline`) so it only offers these pipelines
-     * where they can run; this is the server-side guarantee. A non-visual pipeline passes through.
-     * The workspace block list is read ONCE (for the frontend→service links), never per-frame.
-     */
-    async assertPipelineFrameTypeAllowed(workspaceId, block, agentKinds) {
-        if (!pipelineHasVisualStep({ agentKinds: [...agentKinds] }))
-            return;
-        const frame = await this.contextBuilder.resolveServiceFrame(workspaceId, block.id);
-        // A `frontend` frame is always allowed without listing the workspace; only a non-frontend
-        // frame needs the link scan, so defer the (single) block-list read until then.
-        if (frame?.type === 'frontend')
-            return;
-        const blocks = await this.blockRepository.listByWorkspace(workspaceId);
-        if (frameAllowsVisualPipeline(frame, blocks))
-            return;
-        throw new ConflictError('This pipeline includes a UI-testing step, so it can only run on a frontend service (or a ' +
-            'backend service that has a frontend linked to it). Move the task under a frontend, link ' +
-            'a frontend to this service, or pick a pipeline without UI-testing steps.', 'visual_pipeline_no_frontend', { frameType: frame?.type ?? null });
-    }
-    /**
-     * Guard a Tester pipeline's start on the service frame's declared provisioning being runnable.
-     * The Tester needs SOME way to stand its system up: `infraless` (or none declared) runs with no
-     * infra; `docker-compose`/`kubernetes`/`custom` are all provisioned by the single Deployer step
-     * through a workspace handler, so one must resolve for the service's type. A `frontend` frame is
-     * gated instead on having a live service under test. Throws an actionable {@link ConflictError}
-     * (`tester_infra_unsupported` for the frontend case, `provision_type_unhandled` for a missing
-     * handler); passes through when the provisioning seam is unwired (tests / no environment
-     * integration), like the other optional start guards. `initiatedBy` is threaded into
-     * `canProvision` so the run initiator's local per-user handler OVERRIDES resolve exactly as they
-     * do at provision time (and as the Deployer-config gate does) — else a valid override-only local
-     * setup would be falsely refused here while the deployer would actually provision it.
-     */
-    async assertTesterInfraConfigured(workspaceId, block, initiatedBy) {
-        // A `frontend` frame (the self-contained UI-test flow) is gated on having a live service
-        // under test, NOT on a provision type — resolved first and short-circuiting the backend
-        // branch. Only enforce it when the environment seam is wired (else, like the other optional
-        // start guards, pass through so tests / no-env deployments run unchanged).
-        const frontend = await this.contextBuilder.resolveFrontendConfig(workspaceId, block);
-        if (frontend) {
-            if (!this.environmentProvisioning)
-                return;
-            const decision = decideTesterInfra({
-                frontend: {
-                    hasServiceBindings: hasServiceBinding(frontend.config),
-                    hasLiveService: hasLiveServiceBinding(frontend.bindings),
-                },
-                provisionType: undefined,
-                handlerResolves: true,
-            });
-            if (decision.ok)
-                return;
-            throw new ConflictError(TESTER_INFRA_MESSAGES[decision.reason], 'tester_infra_unsupported', {
-                infraReason: decision.reason,
-            });
-        }
-        const service = await this.contextBuilder.resolveServiceConfig(workspaceId, block);
-        // A `library` frame (not `liveTestable`) runs its unit/integration suite IN-CONTAINER — any
-        // repo-local docker-compose is test infra stood up on localhost, never a Deployer-provisioned
-        // env — so the tester never needs a workspace handler. Pass through regardless of provisioning.
-        if (service?.type && !frameProfile(service.type).liveTestable)
-            return;
-        const provisioning = service?.provisioning;
-        // `docker-compose`/`kubernetes`/`custom` are all provisioned by the Deployer via a workspace
-        // handler, so resolve it lazily — and only when the provisioning seam is wired (else pass
-        // through, treating it as resolvable). `infraless`/none needs no handler.
-        const needsHandler = provisioning?.type === 'docker-compose' ||
-            provisioning?.type === 'kubernetes' ||
-            provisioning?.type === 'custom';
-        const handlerResolves = needsHandler && this.environmentProvisioning
-            ? (await this.environmentProvisioning.canProvision(workspaceId, provisioning, initiatedBy))
-                .ok
-            : true;
-        const decision = decideTesterInfra({ provisionType: provisioning?.type, handlerResolves });
-        if (decision.ok)
-            return;
-        // The only backend-branch refusal is a provision type with no resolvable handler.
-        throw new ConflictError(TESTER_INFRA_MESSAGES[decision.reason], 'provision_type_unhandled', {
-            provisionType: provisioning.type,
-        });
-    }
-    /**
-     * Fail fast when a `docker-compose`/`kubernetes`/`custom` service's chain would dead-end at an
-     * env-consumer (tester / human-test / playwright) because no enabled `deployer` provisions the
-     * environment before it — the exact silent dead-end this initiative fixes (the tester picks
-     * ephemeral mode from the provision type but finds no coordinates). The pure ordering check lives
-     * in {@link needsDeployerBeforeConsumer}; here we resolve the service's provision type (only when a
-     * consumer is present, so consumer-less chains skip the read) and translate a positive verdict
-     * into an actionable {@link ConflictError}. Pass-through for infraless/frontend services and for
-     * chains with a deployer before the first consumer.
-     */
-    async assertDeployerBeforeConsumer(workspaceId, block, agentKinds, enabled) {
-        const hasConsumer = agentKinds.some((kind, i) => enabled?.[i] !== false && ENV_CONSUMER_KINDS.includes(kind));
-        if (!hasConsumer)
-            return;
-        const service = await this.contextBuilder.resolveServiceConfig(workspaceId, block);
-        // A `library` frame stands nothing up via the Deployer (its tester runs the suite in-container),
-        // so a missing Deployer before the tester is never a dead-end — pass through like `infraless`.
-        if (service?.type && !frameProfile(service.type).deployable)
-            return;
-        if (!needsDeployerBeforeConsumer(agentKinds, enabled, service?.provisioning?.type))
-            return;
-        throw new ConflictError(`This service provisions a '${service.provisioning.type}' environment, but this pipeline ` +
-            'has no Deployer step before its first Tester / human-test step, so the environment would ' +
-            'never be stood up. Reseed this pipeline to the latest built-in (which includes a Deployer) ' +
-            'and start a new run, or set the service to docker-compose / infraless.', 'deployer_required_before_tester', { provisionType: service.provisioning.type });
-    }
-    /**
-     * Guard a pipeline that INCLUDES an enabled `deployer` step on its ephemeral-environment config
-     * being FULL + CORRECT on BOTH sides of the "what/where ÷ how" split, so a misconfigured
-     * environment fails LOUDLY at start with a fixable pointer instead of mid-run: a `kubernetes` /
-     * `custom` service silently failing its async provision, or a `docker-compose` one whose deployer
-     * NO-OPS because no handler resolves (the exact silent dead-ends this initiative closes). It
-     * checks, in order of the fix a human would make:
-     *   1. the SERVICE's provisioning config is complete for its declared type (manifest source /
-     *      compose path / custom-manifest id) — else `deployer_service_provisioning_incomplete`;
-     *   2. a WORKSPACE handler resolves for the type — else `provision_type_unhandled` (the same
-     *      reason the Tester gate raises; a MISSING/ambiguous handler, not a broken one);
-     *   3. (bonus, best-effort) the resolved deployment integration's live connection PROBES green —
-     *      else `deployer_connection_test_failed`, carrying the provider's failure detail.
-     * Each `ConflictError` carries a machine-readable reason + details the SPA deep-links off to the
-     * exact fix surface. Pass-through for `infraless`/undeclared services (the deployer stands nothing
-     * up) and when the environment seam is unwired (tests / no-env deployments), like the other
-     * optional start guards.
-     */
-    async assertDeployerConfigured(workspaceId, block, agentKinds, enabled, initiatedBy) {
-        if (!this.environmentProvisioning)
-            return;
-        if (!hasEnabledDeployerStep(agentKinds, enabled))
-            return;
-        const service = await this.contextBuilder.resolveServiceConfig(workspaceId, block);
-        // A Deployer on a `library` frame (not `deployable`) is a safe no-op regardless of any declared
-        // provisioning — the runtime deploy loop records a library skip — so there is nothing to
-        // validate. Checked BEFORE the provisioning branch, since a library may declare a compose path
-        // as repo-local TEST infra (not a deployable env).
-        if (service?.type && !frameProfile(service.type).deployable)
-            return;
-        const provisioning = service?.provisioning;
-        // A Deployer on an `infraless`/undeclared service is a safe no-op (nothing to provision), so
-        // there is nothing to validate — matching the deployer's own skip in advanceDeployerFrames.
-        if (!provisioning || provisioning.type === 'infraless')
-            return;
-        const type = provisioning.type;
-        const serviceIssues = deployerServiceConfigIssues(provisioning);
-        // `canProvision` is a single batched handler read (no decrypt / no N+1); safe to run eagerly.
-        // Pass the initiator so a local per-user handler override resolves exactly as provisioning does
-        // (else a valid override-only local setup would be falsely reported as unhandled).
-        const handlerResolution = await this.environmentProvisioning.canProvision(workspaceId, provisioning, initiatedBy);
-        // Only probe the LIVE connection when the structural config is sound — a network probe is
-        // wasted (and its verdict misleading) while the service config is incomplete or no handler
-        // resolves. A probe FAULT (transient network / provider-build hiccup) is not a definitive
-        // "connection broken" verdict, so swallow it and let the async provision surface a real fault
-        // rather than blocking the start on a flake.
-        let connectionTest;
-        if (serviceIssues.length === 0 && handlerResolution.ok) {
-            try {
-                connectionTest =
-                    (await this.environmentProvisioning.testProvisioning(workspaceId, provisioning, initiatedBy)) ?? undefined;
-            }
-            catch {
-                connectionTest = undefined;
-            }
-        }
-        const decision = decideDeployerConfig({
-            provisionType: type,
-            serviceIssues,
-            handlerResolution,
-            ...(connectionTest ? { connectionTest } : {}),
-        });
-        if (decision.ok)
-            return;
-        if (decision.reason === 'service-config-incomplete') {
-            // Deep-link target: the service FRAME's environment config (the inspector / compose wizard).
-            const frameId = block.level === 'frame'
-                ? block.id
-                : ((await this.contextBuilder.resolveServiceFrameId(workspaceId, block.id)) ?? undefined);
-            throw new ConflictError(`This service provisions a '${type}' environment via the Deployer, but its environment ` +
-                `configuration is incomplete (missing: ${decision.missing.join(', ')}). Complete the ` +
-                "service's environment configuration before starting.", 'deployer_service_provisioning_incomplete', { provisionType: type, missing: [...decision.missing], ...(frameId ? { frameId } : {}) });
-        }
-        if (decision.reason === 'workspace-unhandled') {
-            throw new ConflictError(`This service provisions a '${type}' environment via the Deployer, but this workspace has ` +
-                (decision.handlerReason === 'type-mismatch'
-                    ? `more than one handler matching it — pin a manifest id to disambiguate, `
-                    : `no infrastructure handler configured for that type — `) +
-                'configure a handler (Infrastructure → Test environments), or set the service to ' +
-                'infraless, before starting.', 'provision_type_unhandled', { provisionType: type });
-        }
-        // decision.reason === 'connection-failed'
-        throw new ConflictError(`The '${type}' deployment integration for this service isn't working: ` +
-            `${decision.message ?? 'the connection test failed'}. Check the handler's endpoint and ` +
-            'credentials (Infrastructure → Test environments) and re-test the connection, then start ' +
-            'again.', 'deployer_connection_test_failed', { provisionType: type, ...(decision.message ? { detail: decision.message } : {}) });
-    }
-    /**
-     * Guard a pipeline's start when it carries an agent kind that RELIES on binary-artifact
-     * storage (the {@link BINARY_STORAGE_TRAIT}, e.g. the UI Tester, which uploads its
-     * screenshots there). Such a run would otherwise dispatch and then fail/degrade with no
-     * place to store its artifacts, so refuse it up-front with a clear, actionable
-     * `binary_storage_unconfigured` conflict the SPA turns into a "configure storage" prompt.
-     * The check is trait-driven so it stays universal: a future artifact-producing kind just
-     * carries the trait. Pass-through when no store resolver is wired (tests/conformance with
-     * no storage) — matching the other optional start guards.
-     */
-    async assertBinaryStorageConfigured(workspaceId, agentKinds) {
-        if (!agentKinds.some((kind) => hasTrait(kind, BINARY_STORAGE_TRAIT, this.agentKindRegistry)))
-            return;
-        const resolve = this.resolveBinaryArtifactStore;
-        if (!resolve)
-            return;
-        const store = await resolve(workspaceId);
-        if (store)
-            return;
-        throw new ConflictError('This pipeline includes an agent that needs binary storage (e.g. the UI Tester, which uploads its screenshots), but this account has no content storage configured. Configure content storage to run it.', 'binary_storage_unconfigured');
-    }
-    /**
-     * 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).
-     */
-    async assertProvidersConfiguredForPipeline(workspaceId, block, agentKinds, initiatedBy) {
-        if (!this.resolveProviderCapabilities)
-            return;
-        const caps = await this.resolveProviderCapabilities(workspaceId, initiatedBy);
-        const runsInline = this.inlineHarnessRef;
-        // Two failure buckets, so the error can steer the fix precisely:
-        //  - `unconfigured`: no usable provider AT ALL (container or inline) — add a key/sub/CF.
-        //  - `inlineUnsatisfiable`: usable for a container step but NOT for an INLINE step — a
-        //    subscription-only model an inline `generateText` call can't drive (and this
-        //    deployment can't run the harness inline). The remedy is different (pin an
-        //    inline-capable model, or a preset whose inline steps resolve to one), so a subscription
-        //    model that satisfies the container steps but strands the reviewer/brainstorm/estimator
-        //    is refused up front instead of failing mid-run against an ungated env default.
-        //  - `policyBlocked`: the account-wide model-family policy blocks the model on its
-        //    effective route — a distinct, more actionable reason than "unconfigured", so it is
-        //    checked FIRST and short-circuits the other buckets for that id.
-        const unconfigured = new Set();
-        const inlineUnsatisfiable = new Set();
-        const policyBlocked = new Set();
-        const check = (id, inline) => {
-            if (!id)
-                return;
-            if (caps.modelPolicy &&
-                !isAllowedByFamilyPolicy(id, resolveModelRef(id, caps)?.provider, caps.modelPolicy)) {
-                policyBlocked.add(id);
-                return;
-            }
-            if (!isModelUsable(id, caps))
-                unconfigured.add(id);
-            else if (inline && !isModelUsableInline(id, caps, runsInline))
-                inlineUnsatisfiable.add(id);
-        };
-        if (block.modelId) {
-            // A block-level pin applies to every step; it must satisfy an inline step too when the
-            // pipeline has one.
-            check(block.modelId, agentKinds.some((kind) => isInlineModelStep(kind, this.agentKindRegistry)));
-        }
-        else if (this.resolveWorkspaceModelDefault) {
-            // Independent per-kind resolutions on the start path — run them concurrently.
-            const ids = await Promise.all(agentKinds.map((kind) => this.resolveWorkspaceModelDefault(workspaceId, kind, block.modelPresetId)));
-            agentKinds.forEach((kind, i) => check(ids[i], isInlineModelStep(kind, this.agentKindRegistry)));
-        }
-        if (policyBlocked.size > 0) {
-            throw new ConflictError(`This pipeline uses models blocked by the account's model-family policy: ` +
-                `${[...policyBlocked].join(', ')}. Pick a model from an allowed family (or a ` +
-                'residency-guaranteed route), or ask an account admin to adjust the policy.', 'model_policy_blocked', { models: [...policyBlocked] });
-        }
-        if (unconfigured.size > 0) {
-            throw new ConflictError(`This pipeline uses models with no configured provider: ${[...unconfigured].join(', ')}. ` +
-                'Add an API key for the provider, connect a subscription, or enable Cloudflare AI ' +
-                'before starting.', 'providers_unconfigured', { models: [...unconfigured] });
-        }
-        if (inlineUnsatisfiable.size > 0) {
-            throw new ConflictError(`This pipeline has inline steps (e.g. the requirements reviewer) whose model ` +
-                `cannot run inline: ${[...inlineUnsatisfiable].join(', ')}. A subscription-only model ` +
-                '(Claude / GPT / GLM) runs only in the container agents, not the inline reviewers — ' +
-                'and this deployment has no inline harness. Pick a model preset whose inline steps ' +
-                'resolve to a provider-backed model (a direct API key, OpenRouter, or Cloudflare AI), ' +
-                'or run local mode with the ambient Claude Code / Codex CLI enabled.', 'preset_unsatisfiable', { models: [...inlineUnsatisfiable] });
-        }
-    }
-    /**
-     * Refuse to START / RETRY a run when the workspace has reached its spend budget AND the
-     * pipeline has at least one budget-METERED step. A `0` (or exhausted) budget is a
-     * deliberate "no paid spend" setting, but it must surface as a clear, up-front error here
-     * rather than a silent mid-run pause. Steps that incur no metered cost — a connected
-     * subscription model, or a keyless local-runner model — are exempt, so a workspace that
-     * runs ONLY local/subscription models starts normally even at a `0` budget. Best-effort:
-     * with no capability resolver wired (tests/unconfigured) it is skipped and the mid-run
-     * gate still guards. Before any side effects, matching the other start guards.
-     */
-    async assertBudgetAllowsPipeline(workspaceId, block, agentKinds, initiatedBy) {
-        const accountId = await this.workspaceRepository.accountOf(workspaceId);
-        if (!(await this.spend.isOverBudget(workspaceId, { accountId, userId: initiatedBy })))
-            return;
-        if (!this.resolveProviderCapabilities)
-            return;
-        const caps = await this.resolveProviderCapabilities(workspaceId, initiatedBy);
-        const ids = [];
-        if (block.modelId) {
-            ids.push(block.modelId);
-        }
-        else if (this.resolveWorkspaceModelDefault) {
-            ids.push(...(await Promise.all(agentKinds.map((kind) => this.resolveWorkspaceModelDefault(workspaceId, kind, block.modelPresetId)))));
-        }
-        else {
-            ids.push(undefined);
-        }
-        if (!ids.some((id) => this.modelIdIsMetered(id, caps)))
-            return;
-        throw new ConflictError('This run has reached a spend budget (workspace, account, or user). New runs on metered ' +
-            'models are paused until the budget is raised or the billing period resets. A task pinned ' +
-            'to a local model or a connected subscription still runs.');
-    }
-    /**
-     * Whether a model id will incur metered monetary cost for THIS workspace. Non-metered:
-     * a subscription model whose vendor is connected ("subscriptions always win"), or a
-     * local-runner model (keyless, on the user's own endpoint). Everything else — including
-     * env-default routing (an absent id) and Cloudflare Workers AI — is treated as metered.
-     */
-    modelIdIsMetered(id, caps) {
-        const sub = subscriptionOptionFor(id);
-        if (sub && caps.subscriptionVendors.has(sub.vendor))
-            return false;
-        const ref = resolveModelRef(id, caps);
-        if (!ref)
-            return true;
-        if (ref.harness === 'claude-code' || ref.harness === 'codex')
-            return false;
-        return !isLocalRunner(ref.provider);
-    }
-    /**
-     * The config/resource preconditions a run must satisfy to START, RETRY **or** RESTART:
-     * everything that depends on the workspace environment + the steps being run, and NOT on
-     * whether this is a fresh run or a replacement. All three entry points call this so they
-     * can't drift — a guard added to one but silently missing from the other is exactly how a
-     * subscription-only preset slipped past retry and failed mid-run against the routing default.
-     * All checks are read-only and run BEFORE any side effects, each throwing an actionable
-     * {@link ConflictError}.
-     *
-     * The `shape` is the effective chain that will run, NOT the current pipeline definition: a
-     * fresh start passes the pipeline, while a retry/restart passes the STORED steps (via
-     * {@link runnableShapeOf}) so the guard validates exactly what re-executes — a pipeline
-     * edited out of band since the run started can't falsely refuse (or silently skip a check
-     * for) a step that isn't actually being re-driven.
-     *
-     * The concurrency (task-limit) and dependency gates are deliberately NOT here — they are
-     * start-only (a retry replaces the failed run rather than adding a new concurrent one, and a
-     * re-drive of an already-started task isn't re-gated on its dependencies).
-     */
-    async assertRunnable(workspaceId, block, shape, initiatedBy) {
-        // Reject a structurally-invalid chain (a misplaced companion or estimate-gating without a
-        // preceding task-estimator). The builder also rejects these at save, but a pipeline can
-        // become invalid out of band.
-        validatePipelineShape(shape);
-        // The Initiative Planning kinds run ONLY on an `initiative`-level block, and an
-        // initiative block accepts ONLY such a chain — bidirectional, and here in the shared
-        // guard so start/retry/restart can't drift on it.
-        assertInitiativeShapeAllowed(block, shape.agentKinds);
-        // A chain with visual steps (`tester-ui` / `visual-confirmation`) needs a UI to exercise:
-        // it can only run on a `frontend` frame or a frame a frontend links to — else a `tester-ui`
-        // step has no app to drive.
-        await this.assertPipelineFrameTypeAllowed(workspaceId, block, shape.agentKinds);
-        // A chain with a Tester needs the service's declared provisioning to be runnable
-        // (`infraless`/none = no infra; `docker-compose`/`kubernetes`/`custom` = a workspace handler).
-        if (shape.agentKinds.some(isTesterKind)) {
-            await this.assertTesterInfraConfigured(workspaceId, block, initiatedBy);
-        }
-        // A `docker-compose`/`kubernetes`/`custom` service whose enabled chain reaches an env-consumer
-        // (tester / human-test / playwright) with NO enabled `deployer` before it would dead-end inside
-        // the consumer — nothing provisions the environment it reads. Fail fast with an actionable error.
-        await this.assertDeployerBeforeConsumer(workspaceId, block, shape.agentKinds, shape.enabled);
-        // A chain that INCLUDES an enabled Deployer needs the service's provisioning config (the
-        // "what/where") AND the workspace's infra handler (the "how") complete + correct — and, best
-        // effort, the deployment integration's live connection working — so a misconfigured environment
-        // fails loudly here with a fix-it pointer instead of an async failed env (or a silent no-op).
-        await this.assertDeployerConfigured(workspaceId, block, shape.agentKinds, shape.enabled, initiatedBy);
-        // A chain carrying an agent that relies on binary-artifact storage (the UI Tester uploads
-        // screenshots) needs the account to have storage configured.
-        await this.assertBinaryStorageConfigured(workspaceId, shape.agentKinds);
-        // A workspace that delegates container agents to a runner pool needs that pool registered
-        // (local mode opt-in). No-op on Cloudflare/Node (fixed backend) and when delegation is off.
-        await this.assertAgentBackendConfigured?.(workspaceId);
-        // Every step's canonical model must have a usable provider — a container step needs any
-        // usable flavour, an INLINE step needs an inline-usable one (a subscription-only model can't
-        // run inline without an inline harness). This is the gate a retry used to skip.
-        await this.assertProvidersConfiguredForPipeline(workspaceId, block, shape.agentKinds, initiatedBy);
-        // Refuse a metered run once the spend budget is reached (a clear error rather than a silent
-        // mid-run pause). A local/subscription-only pipeline is exempt.
-        await this.assertBudgetAllowsPipeline(workspaceId, block, shape.agentKinds, initiatedBy);
-    }
-    /**
-     * The {@link PipelineShape} a retry/restart re-drives: the stored run's steps ARE the enabled,
-     * ordered chain that will run again, so {@link assertRunnable} validates exactly what
-     * re-executes rather than the current pipeline definition (which may have been edited out of
-     * band since the run started). Disabled steps were already filtered out at start, so every
-     * stored step is enabled.
-     */
-    runnableShapeOf(steps) {
-        return {
-            agentKinds: steps.map((s) => s.agentKind),
-            gating: steps.map((s) => s.gating ?? null),
-            // The QC companion's live step-state carries the same `gating` config the pipeline set, so
-            // the tester-QC gating validation re-runs on a retry against exactly what re-executes.
-            testerQuality: steps.map((s) => s.testerQuality ?? null),
-            // The per-step options bag (carrying a `skill` step's `skillId`) is copied onto the run
-            // step at start, so the skill-step validation re-runs on retry against what re-executes.
-            stepOptions: steps.map((s) => s.stepOptions ?? null),
-        };
-    }
     /** Start a pipeline against a block, replacing any prior run on it. */
     async start(workspaceId, blockId, pipelineId, 
     /**
@@ -976,7 +564,7 @@ export class ExecutionService {
         // Shared config/resource preconditions (pipeline shape, frame type, tester infra, binary
         // storage, agent backend, provider/preset satisfiability, budget) — the SAME gate a retry
         // runs, so the two can't drift. See assertRunnable.
-        await this.assertRunnable(workspaceId, block, pipeline, initiatedBy);
+        await this.admission.assertRunnable(workspaceId, block, pipeline, initiatedBy);
         // A Ralph-loop step needs a programmatic completion command (its exit condition); refuse to
         // start a misconfigured run rather than dispatch a validation-less coding pass that never
         // gates. The command is a per-task agent-config value (the SPA also requires it at creation).
@@ -990,12 +578,12 @@ export class ExecutionService {
         // re-gated on its dependencies.
         // Enforce the workspace's per-service running-task limit (off by default) — a clear,
         // actionable error before any side effects, so the human knows why the start was refused.
-        await this.assertWithinTaskLimit(workspaceId, block);
+        await this.admission.assertWithinTaskLimit(workspaceId, block);
         // Hard dependency gate: a task cannot start while any block it `dependsOn` is unfinished
         // (not yet `done`/merged). Enforced server-side so it holds for manual starts, recurring
         // fires, auto-start propagation and direct API calls alike — the frontend's runnable
         // check is only a hint. Before any side effects so nothing is torn down on a refusal.
-        await this.assertDependenciesMet(workspaceId, block);
+        await this.admission.assertDependenciesMet(workspaceId, block);
         // Mint the activation next: if the credential can't be unlocked, fail before
         // tearing down the block's prior run or creating a new one.
         const executionId = this.idGenerator.next('exec');
@@ -1150,103 +738,6 @@ export class ExecutionService {
         await this.runStateMachine.emitInstance(workspaceId, instance);
         return instance;
     }
-    /**
-     * 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).
-     */
-    /**
-     * Refuse a task start while any of its dependencies is unfinished. A task may only run
-     * once every block it `dependsOn` has reached `done` (its PR merged). No-ops for
-     * non-task blocks and for tasks with no dependencies. Throws a {@link ConflictError}
-     * (→ 409, shown as a toast) naming the unfinished blockers so the human knows why.
-     */
-    async assertDependenciesMet(workspaceId, block) {
-        if (block.level !== 'task' || block.dependsOn.length === 0)
-            return;
-        const blocks = await this.augmentWithCrossWorkspaceDeps(await this.blockRepository.listByWorkspace(workspaceId), block.dependsOn);
-        if (dependenciesMet(blocks, block.id))
-            return;
-        const blockers = unmetDependencies(blocks, block.id);
-        const names = blockers.map((b) => `"${b.title}"`).join(', ');
-        throw new ConflictError(`This task is blocked by ${blockers.length} unfinished dependenc${blockers.length === 1 ? 'y' : 'ies'}${names ? ` (${names})` : ''}. Finish them before starting this task.`, 'dependencies_unmet', { count: blockers.length, blockers: blockers.map((b) => b.title) });
-    }
-    /**
-     * Augment a workspace's block list (in place) with any dependency blocks referenced by
-     * `depIds` that aren't already present — a `dependsOn` edge can point at a task homed in a
-     * DIFFERENT workspace (a shared/mounted service). Resolved via the cross-workspace
-     * {@link BlockRepository.findByIds} (one batched query, not a point-read per id), so a
-     * shared-service blocker is evaluated by its real status instead of being silently treated
-     * as satisfied (missing ⇒ done). Returns the same (now-augmented) array for chaining.
-     */
-    async augmentWithCrossWorkspaceDeps(blocks, depIds) {
-        const have = new Set(blocks.map((b) => b.id));
-        const missing = [...new Set(depIds)].filter((id) => !have.has(id));
-        if (missing.length === 0)
-            return blocks;
-        for (const found of await this.blockRepository.findByIds(missing)) {
-            blocks.push(found.block);
-        }
-        return blocks;
-    }
-    async assertWithinTaskLimit(workspaceId, block) {
-        const settingsService = this.workspaceSettingsService;
-        if (!settingsService || block.level !== 'task')
-            return;
-        const settings = await settingsService.get(workspaceId);
-        if (settings.taskLimitMode === 'off')
-            return;
-        const all = await this.blockRepository.listByWorkspace(workspaceId);
-        const byId = new Map(all.map((b) => [b.id, b]));
-        // Walk up to the owning service frame.
-        let frame = block;
-        let guard = 0;
-        while (frame && frame.level !== 'frame' && guard++ < 1000) {
-            frame = frame.parentId ? byId.get(frame.parentId) : undefined;
-        }
-        if (!frame || frame.level !== 'frame')
-            return; // orphan task — nothing to scope a service limit to
-        const frameId = frame.id;
-        const underFrame = (b) => {
-            let cur = b;
-            let hops = 0;
-            while (cur && hops++ < 1000) {
-                if (cur.id === frameId)
-                    return true;
-                cur = cur.parentId ? byId.get(cur.parentId) : undefined;
-            }
-            return false;
-        };
-        // Lean projection of the workspace's live runs (block + status only) — avoids loading and
-        // JSON-decoding every historical run's `detail` just to read the handful of live block ids.
-        const live = await this.executionRepository.listLive(workspaceId);
-        const liveBlockIds = new Set(live.map((e) => e.blockId));
-        const siblingTasks = all.filter((b) => b.level === 'task' && b.id !== block.id && underFrame(b));
-        if (settings.taskLimitMode === 'shared') {
-            const limit = settings.taskLimitShared ?? 0;
-            const running = siblingTasks.filter((b) => liveBlockIds.has(b.id)).length;
-            if (running >= limit) {
-                throw new ConflictError(`"${frame.title}" is already running ${running} of ${limit} allowed task(s). ` +
-                    `Wait for one to finish before starting another.`, 'task_limit_reached', { frame: frame.title, limit, running });
-            }
-            return;
-        }
-        // per_type: only the configured types are capped; an unconfigured type is unbounded.
-        const type = block.taskType ?? 'feature';
-        const perType = (settings.taskLimitPerType ?? {});
-        const limit = perType[type];
-        if (limit == null)
-            return;
-        const running = siblingTasks.filter((b) => liveBlockIds.has(b.id) && (b.taskType ?? 'feature') === type).length;
-        if (running >= limit) {
-            throw new ConflictError(`"${frame.title}" is already running ${running} of ${limit} allowed ${type} task(s). ` +
-                `Wait for one to finish before starting another ${type} task.`, 'task_limit_reached', { frame: frame.title, limit, running, taskType: type });
-        }
-    }
     /**
      * 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
@@ -1513,178 +1004,6 @@ export class ExecutionService {
             throw new ConflictError('Resolve the follow-up companion through its window (file / send back / answer / dismiss), not the approval gate');
         }
     }
-    /**
-     * 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.
-     */
-    buildRequirementsKind() {
-        const require = () => {
-            if (!this.requirementReviewService?.enabled) {
-                throw new ConflictError('The requirements reviewer is not configured');
-            }
-            return this.requirementReviewService;
-        };
-        return {
-            agentKind: REQUIREMENTS_REVIEW_AGENT_KIND,
-            entityName: 'Requirement review',
-            enabled: () => !!this.requirementReviewService?.enabled,
-            getForBlock: (ws, blockId) => require().getForBlock(ws, blockId),
-            review: (ws, block, preset) => require().review(ws, block.id, {
-                maxIterations: preset.maxRequirementIterations,
-                concernThreshold: preset.maxRequirementConcernAllowed,
-            }),
-            reReview: (ws, reviewId, preset) => require().reReview(ws, reviewId, { concernThreshold: preset.maxRequirementConcernAllowed }),
-            incorporate: async (ws, _blockId, reviewId, feedback) => {
-                await require().incorporate(ws, reviewId, { feedback });
-            },
-            markIncorporated: (ws, reviewId) => require().markIncorporated(ws, reviewId),
-            markReReviewing: (ws, reviewId) => require().markReReviewing(ws, reviewId),
-            markIncorporating: (ws, reviewId) => require().markIncorporating(ws, reviewId),
-            grantExtraRound: (ws, reviewId) => require().grantExtraRound(ws, reviewId),
-            prepareRecommendations: (ws, reviewId, items) => require().prepareRecommendations(ws, reviewId, items),
-            markRecommendationPending: (ws, reviewId, recId, note) => require().markRecommendationPending(ws, reviewId, recId, note),
-            fillRecommendations: async (ws, blockId) => {
-                const svc = require();
-                const review = assertFound(await svc.getForBlock(ws, blockId), 'Requirement review', blockId);
-                await svc.fillPendingRecommendations(ws, review.id, {
-                    onProgress: (r) => this.events.requirementReviewChanged?.(ws, r) ?? Promise.resolve(),
-                });
-                return assertFound(await svc.getForBlock(ws, blockId), 'Requirement review', blockId);
-            },
-            autoRecommend: async (ws, blockId) => {
-                const svc = require();
-                const review = assertFound(await svc.getForBlock(ws, blockId), 'Requirement review', blockId);
-                await svc.autoRecommend(ws, review.id, {
-                    onProgress: (r) => this.events.requirementReviewChanged?.(ws, r) ?? Promise.resolve(),
-                });
-            },
-            emit: (ws, review) => this.events.requirementReviewChanged?.(ws, review) ?? Promise.resolve(),
-        };
-    }
-    /**
-     * 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.
-     */
-    buildClarityKind() {
-        const require = () => {
-            if (!this.clarityReviewService) {
-                throw new ConflictError('The clarity reviewer is not configured');
-            }
-            return this.clarityReviewService;
-        };
-        return {
-            agentKind: CLARITY_REVIEW_AGENT_KIND,
-            // Enabled whenever the clarity STORE is wired — the bug-triage seed/auto-pass path is
-            // deterministic (driven by the upstream investigator's structured triage) and needs no
-            // reviewer model, so the gate must activate even with no model configured. The LLM
-            // review/incorporate/re-review paths still resolve their own model (and degrade gracefully
-            // when unwired: no investigation + no model ⇒ the review closure auto-passes).
-            entityName: 'Clarity review',
-            enabled: () => !!this.clarityReviewService,
-            getForBlock: (ws, blockId) => require().getForBlock(ws, blockId),
-            review: async (ws, block, preset) => {
-                const svc = require();
-                const structured = await this.structuredInvestigationForBlock(ws, block.id);
-                let review;
-                if (structured) {
-                    // An upstream structured `bug-investigator`: seed the gate from its triage — NO reviewer
-                    // LLM. `clear` → auto-pass; `needs_clarification` → one blocking finding per question.
-                    // The investigator explicitly asked for clarification, so those questions ALWAYS park
-                    // for a human — the requirements-review concern tolerance (`maxRequirementConcernAllowed`,
-                    // which governs the requirements reviewer, not bug triage) must not silently auto-pass
-                    // them — hence a fixed `none` threshold here rather than the preset's.
-                    review = await svc.seedReview(ws, block.id, {
-                        clarity: structured.clarity,
-                        questions: structured.questions,
-                        maxIterations: preset.maxRequirementIterations,
-                        concernThreshold: 'none',
-                    });
-                }
-                else if (!svc.enabled) {
-                    // No structured investigation and no reviewer model: nothing to review against, so
-                    // auto-pass (equivalent to the old pass-through when the reviewer wasn't configured).
-                    review = await svc.seedReview(ws, block.id, {
-                        clarity: 'clear',
-                        questions: [],
-                        maxIterations: preset.maxRequirementIterations,
-                        concernThreshold: preset.maxRequirementConcernAllowed,
-                    });
-                }
-                else {
-                    review = await svc.review(ws, block.id, {
-                        maxIterations: preset.maxRequirementIterations,
-                        concernThreshold: preset.maxRequirementConcernAllowed,
-                        investigation: await this.investigationForBlock(ws, block.id),
-                    });
-                }
-                // Whenever the gate parks with open questions — from the deterministic seed OR the LLM
-                // reviewer — best-effort echo them onto the linked tracker issue (answers still arrive
-                // in-app). A settled/auto-passed review echoes nothing; a tracker outage never fails the run.
-                await this.echoClarityQuestions(ws, block.id, review);
-                return review;
-            },
-            reReview: async (ws, reviewId, preset) => {
-                const svc = require();
-                // No reviewer model wired: a re-review can't run, so settle the loop (converge) instead of
-                // throwing — the deterministic seed path can reach a park with no model configured.
-                if (!svc.enabled)
-                    return svc.markIncorporated(ws, reviewId);
-                return svc.reReview(ws, reviewId, { concernThreshold: preset.maxRequirementConcernAllowed });
-            },
-            incorporate: async (ws, blockId, reviewId, feedback) => {
-                const svc = require();
-                // No reviewer model: can't LLM-fold the answers into a clarified report, so settle the
-                // review as-is (the run advances on the raw report + the recorded answers) instead of
-                // throwing — keeps the model-free seed path resolvable.
-                if (!svc.enabled) {
-                    await svc.markIncorporated(ws, reviewId);
-                    return;
-                }
-                const investigation = await this.investigationForBlock(ws, blockId);
-                await svc.incorporate(ws, reviewId, { feedback, investigation });
-            },
-            markIncorporated: (ws, reviewId) => require().markIncorporated(ws, reviewId),
-            markReReviewing: (ws, reviewId) => require().markReReviewing(ws, reviewId),
-            markIncorporating: (ws, reviewId) => require().markIncorporating(ws, reviewId),
-            grantExtraRound: (ws, reviewId) => require().grantExtraRound(ws, reviewId),
-            emit: (ws, review) => this.events.clarityReviewChanged?.(ws, review) ?? Promise.resolve(),
-        };
-    }
-    /**
-     * A brainstorm (structured-dialogue) subject for {@link reviewGate}, parameterised by stage.
-     * Otherwise identical to the requirements kind — the service handles its own upstream context
-     * (the architecture stage seeds from the refined requirements). The brainstorm services
-     * resolve their model exactly like the requirements reviewer, so the cap knobs are reused.
-     */
-    buildBrainstormKind(stage, agentKind) {
-        const require = () => {
-            const svc = this.brainstormServices?.[stage];
-            if (!svc?.enabled)
-                throw new ConflictError('The brainstorm agent is not configured');
-            return svc;
-        };
-        return {
-            agentKind,
-            entityName: 'Brainstorm session',
-            enabled: () => !!this.brainstormServices?.[stage]?.enabled,
-            getForBlock: (ws, blockId) => require().getForBlock(ws, blockId),
-            review: (ws, block, preset) => require().review(ws, block.id, {
-                maxIterations: preset.maxRequirementIterations,
-                concernThreshold: preset.maxRequirementConcernAllowed,
-            }),
-            reReview: (ws, reviewId, preset) => require().reReview(ws, reviewId, { concernThreshold: preset.maxRequirementConcernAllowed }),
-            incorporate: async (ws, _blockId, reviewId, feedback) => {
-                await require().incorporate(ws, reviewId, { feedback });
-            },
-            markIncorporated: (ws, reviewId) => require().markIncorporated(ws, reviewId),
-            markReReviewing: (ws, reviewId) => require().markReReviewing(ws, reviewId),
-            markIncorporating: (ws, reviewId) => require().markIncorporating(ws, reviewId),
-            grantExtraRound: (ws, reviewId) => require().grantExtraRound(ws, reviewId),
-            emit: (ws, session) => this.events.brainstormSessionChanged?.(ws, session) ?? Promise.resolve(),
-        };
-    }
     /** Pick the brainstorm kind for a stage (the dedicated window drives both via the same loop). */
     brainstormKindFor(stage) {
         return stage === 'architecture'
@@ -1812,71 +1131,6 @@ export class ExecutionService {
         });
         return result;
     }
-    // ---- clarity-review context helpers (bug-report triage) ------------------
-    // The clarity gate triages a block's bug report — optionally enriched by an upstream
-    // `bug-investigator` step's prose output — through the SAME {@link ReviewGateController}
-    // flow as requirements; these two helpers resolve that investigator output as the triage
-    // subject, threaded into the clarity {@link ReviewKind}.
-    /** The latest `bug-investigator` step output on a run (the triage subject), or undefined. */
-    investigationFor(instance) {
-        for (let i = instance.steps.length - 1; i >= 0; i--) {
-            const s = instance.steps[i];
-            if (s.agentKind === BUG_INVESTIGATOR_AGENT_KIND && s.output)
-                return s.output;
-        }
-        return undefined;
-    }
-    /** Resolve a block's investigator output via its current execution (off the gate path). */
-    async investigationForBlock(workspaceId, blockId) {
-        const block = await this.blockRepository.get(workspaceId, blockId);
-        if (!block?.executionId)
-            return undefined;
-        const instance = await this.executionRepository.get(workspaceId, block.executionId);
-        return instance ? this.investigationFor(instance) : undefined;
-    }
-    /**
-     * The latest `bug-investigator` step's STRUCTURED triage on a run — its `clarity` verdict +
-     * `questions` — parsed leniently from `step.custom`. Drives the clarity gate's seed/auto-pass
-     * (see {@link buildClarityKind}): a structured investigator upstream means the gate seeds its
-     * findings from `questions` (or auto-passes on `clarity === 'clear'`) instead of running its
-     * own reviewer LLM. Undefined when no investigator ran or its result wasn't structured (an
-     * older prose investigator, or an unparseable reply) — the gate then falls back to the LLM path.
-     */
-    structuredInvestigationFor(instance) {
-        for (let i = instance.steps.length - 1; i >= 0; i--) {
-            const s = instance.steps[i];
-            if (s.agentKind !== BUG_INVESTIGATOR_AGENT_KIND || s.custom === undefined)
-                continue;
-            const parsed = bugInvestigation.safeParse(s.custom);
-            if (!parsed)
-                return undefined;
-            return { clarity: parsed.clarity, questions: parsed.questions };
-        }
-        return undefined;
-    }
-    /** Resolve a block's structured investigator triage via its current execution. */
-    async structuredInvestigationForBlock(workspaceId, blockId) {
-        const block = await this.blockRepository.get(workspaceId, blockId);
-        if (!block?.executionId)
-            return undefined;
-        const instance = await this.executionRepository.get(workspaceId, block.executionId);
-        return instance ? this.structuredInvestigationFor(instance) : undefined;
-    }
-    /**
-     * Best-effort echo of a parked clarity review's open questions onto the block's linked tracker
-     * issue (see {@link IssueWritebackProvider.postQuestions}). Fires for BOTH the deterministic
-     * investigator seed and the LLM reviewer, so identical human-parked states behave the same. A
-     * settled/auto-passed review (status `incorporated`) or one with no open items echoes nothing,
-     * and a tracker outage never fails the run.
-     */
-    async echoClarityQuestions(workspaceId, blockId, review) {
-        if (!this.issueWriteback || review.status === 'incorporated')
-            return;
-        const questions = review.items.filter((i) => i.status === 'open').map((i) => i.detail);
-        if (questions.length === 0)
-            return;
-        await this.issueWriteback.postQuestions(workspaceId, blockId, questions).catch(() => { });
-    }
     // The clarity / human-testing / visual-confirmation gate-window actions now live on the
     // per-feature sub-facades (`clarityReview` / `humanTest` / `visualConfirm`); see the getters
     // above and {@link gate-window-facades}.
@@ -2050,7 +1304,7 @@ export class ExecutionService {
             return;
         // A dependent's OTHER blockers may live in another workspace (a shared service); resolve
         // them so `dependenciesMet` doesn't treat a cross-workspace blocker as missing-⇒-satisfied.
-        await this.augmentWithCrossWorkspaceDeps(blocks, dependents.flatMap((d) => d.dependsOn));
+        await this.admission.augmentWithCrossWorkspaceDeps(blocks, dependents.flatMap((d) => d.dependsOn));
         // Resolve every dependent's pipeline from ONE workspace list, not a per-dependent
         // point-read in the loop (banned N+1): index the catalog by id, and take the board's
         // "Run" default (the first pipeline) for any dependent with no pinned pipeline.
@@ -2394,7 +1648,7 @@ export class ExecutionService {
         // STORED steps (what the retry actually re-drives), not the current pipeline definition, so
         // an out-of-band pipeline edit can't skew the gate and a deleted pipeline needs no special
         // case. Before any side effects.
-        await this.assertRunnable(workspaceId, block, this.runnableShapeOf(previous.steps), initiatedBy ?? previous.initiatedBy);
+        await this.admission.assertRunnable(workspaceId, block, this.admission.runnableShapeOf(previous.steps), initiatedBy ?? previous.initiatedBy);
         const { steps, currentStep } = planResumedSteps(previous);
         // Mint the activation before replacing the failed run, so a bad password aborts
         // the retry without losing the retryable terminal run.
@@ -2479,7 +1733,7 @@ export class ExecutionService {
         // so it must be gated identically — otherwise a run whose preset can't run every step (e.g. a
         // subscription-only model an inline reviewer can't drive) strands mid-run instead of being
         // refused up front. Before any teardown/side effects.
-        await this.assertRunnable(workspaceId, block, this.runnableShapeOf(previous.steps), initiatedBy ?? previous.initiatedBy);
+        await this.admission.assertRunnable(workspaceId, block, this.admission.runnableShapeOf(previous.steps), initiatedBy ?? previous.initiatedBy);
         // Tear down whatever was driving the run we're about to replace — its per-run
         // container AND its durable driver — before minting the restart. A `done`/`failed`
         // run is already terminal (a no-op teardown), but a still-`running` run would