@lota-sdk/core 0.4.7 → 0.4.9

package/src/services/ownership-dispatcher.service.ts

@@ -4,35 +4,62 @@ import type {
   PlanArtifactRecord,
   PlanArtifactSubmission,
   PlanFailureClass,
-  PlanNodeResultSubmission,
   PlanNodeRunRecord,
   PlanNodeSpec,
   PlanNodeSpecRecord,
   PlanRunRecord,
   PlanSchemaRegistry,
   PlanSpecRecord,
+  PlanNodeOwner,
   PlanDraft,
-  SerializableExecutionPlan,
   UpstreamHandoff,
 } from '@lota-sdk/shared'
+import { Cause, Context, Effect, Layer, Match } from 'effect'
 
-import { agentRoster } from '../config/agent-defaults'
+import type { ResolvedAgentConfig } from '../config/agent-defaults'
 import type { RecordIdInput } from '../db/record-id'
 import { ensureRecordId, recordIdToString } from '../db/record-id'
-import { databaseService } from '../db/service'
+import type { SurrealDBService } from '../db/service'
 import { TABLES } from '../db/tables'
+import { BadRequestError, ConfigurationError, DatabaseError } from '../effect/errors'
+import { isPromiseLike } from '../effect/helpers'
+import { AgentConfigServiceTag, DatabaseServiceTag, RuntimeAdaptersServiceTag } from '../effect/services'
 import { resolvePlanNodeExecutionVisibility, shouldPlanNodeUseVisibleTurn } from '../runtime/execution-plan-visibility'
-import { getRuntimeAdapters } from '../runtime/runtime-extensions'
-import { agentExecutorService } from './agent-executor.service'
-import { monitoringWindowService } from './monitoring-window.service'
-import { planExecutorService } from './plan-executor.service'
-import { planRunService } from './plan-run.service'
-import type { PlanValidationIssueInput } from './plan-validator.service'
-import { pluginExecutorService } from './plugin-executor.service'
-import { skillResolverService } from './skill-resolver.service'
-import { systemExecutorService } from './system-executor.service'
-import { ThreadSchema } from './thread.types'
-import { userService } from './user.service'
+import type { LotaRuntimeAdapters } from '../runtime/runtime-extensions'
+import type { makeAgentExecutorService } from './agent-executor.service'
+import { AgentExecutorServiceTag } from './agent-executor.service'
+import { routeGraphFullEffect } from './graph-full-routing'
+import type { makeMonitoringWindowService } from './monitoring-window.service'
+import { MonitoringWindowServiceTag } from './monitoring-window.service'
+import type { makePlanExecutorService } from './plan/plan-executor.service'
+import { PlanExecutorServiceTag } from './plan/plan-executor.service'
+import { serializeRunFull } from './plan/plan-run-serialization'
+import type { makePlanRunService } from './plan/plan-run.service'
+import { PlanRunServiceTag } from './plan/plan-run.service'
+import type { PlanValidationIssueInput } from './plan/plan-validator.service'
+import type { makePluginExecutorService } from './plugin-executor.service'
+import { PluginExecutorServiceTag } from './plugin-executor.service'
+import type { SkillResolverService } from './skill-resolver.service'
+import { SkillResolverServiceTag } from './skill-resolver.service'
+import type { makeSystemExecutorService } from './system-executor.service'
+import { SystemExecutorServiceTag } from './system-executor.service'
+import { ThreadSchema } from './thread/thread.types'
+import type { makeUserService } from './user.service'
+import { UserServiceTag } from './user.service'
+
+interface OwnershipDispatcherDeps {
+  db: SurrealDBService
+  agentConfig: ResolvedAgentConfig
+  runtimeAdapters: LotaRuntimeAdapters
+  agentExecutor: ReturnType<typeof makeAgentExecutorService>
+  monitoringWindow: ReturnType<typeof makeMonitoringWindowService>
+  planExecutor: ReturnType<typeof makePlanExecutorService>
+  planRun: ReturnType<typeof makePlanRunService>
+  pluginExecutor: ReturnType<typeof makePluginExecutorService>
+  skillResolver: SkillResolverService
+  systemExecutor: ReturnType<typeof makeSystemExecutorService>
+  user: ReturnType<typeof makeUserService>
+}
 
 const STABLE_RUN_STATUSES = new Set(['pending-approval', 'awaiting-human', 'blocked', 'failed', 'completed', 'aborted'])
 const MAX_DISPATCH_ITERATIONS = 64
@@ -101,204 +128,89 @@ function formatDispatchError(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
-class OwnershipDispatcherService {
-  validateDraftExecutors(draft: PlanDraft): PlanValidationIssueInput[] {
-    const issues: PlanValidationIssueInput[] = []
-
-    for (const node of draft.nodes) {
-      if (node.owner.executorType === 'agent') {
-        if (!agentRoster.includes(node.owner.ref)) {
-          issues.push({
-            severity: 'blocking',
-            code: 'agent_executor_missing',
-            message: `Node "${node.label}" references unknown agent executor "${node.owner.ref}".`,
-            nodeId: node.id,
-            detail: { agentId: node.owner.ref },
-          })
-        }
-        continue
-      }
-
-      if (node.owner.executorType === 'plugin') {
-        issues.push(...pluginExecutorService.validateOwner(node.owner, node.id))
-        continue
-      }
-
-      if (node.owner.executorType === 'system') {
-        issues.push(...systemExecutorService.validateOwner(node.owner, node.id))
-        continue
-      }
-
-      if (node.owner.executorType === 'skill') {
-        // Skill owners are validated at execution time via skillResolverService.
-      }
-    }
-
-    return issues
-  }
-
-  async dispatchRunToStableBoundary(params: {
-    runId: RecordIdInput
-    emittedBy: string
-  }): Promise<SerializableExecutionPlan> {
-    const initialRun = await planRunService.getRunById(params.runId)
-    const autoDispatchEnabled = await this.shouldAutoDispatch(initialRun)
-    if (!autoDispatchEnabled) {
-      return this.serializeRun(initialRun.id)
-    }
-
-    let iteration = 0
-    while (iteration < MAX_DISPATCH_ITERATIONS) {
-      const run = await planRunService.getRunById(params.runId)
-      if (STABLE_RUN_STATUSES.has(run.status) || run.status !== 'running' || !run.currentNodeId) {
-        return this.serializeRun(run.id)
-      }
-
-      const spec = await planRunService.getPlanSpecById(run.planSpecId)
-
-      if (spec.executionMode === 'graph-full') {
-        const { globalOrchestratorService } = await import('./global-orchestrator.service')
-        await globalOrchestratorService.routeGraphFull({
-          threadId: recordIdToString(run.threadId, TABLES.THREAD),
-          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
-        })
-        return this.serializeRun(run.id)
-      }
-
-      const nodeSpecRecord = await planRunService.getNodeSpecByNodeId(spec.id, run.currentNodeId)
-      const planNode = toPlanNodeSpec(nodeSpecRecord)
-      if (planNode.owner.executorType === 'user') {
-        return this.serializeRun(run.id)
-      }
-
-      const nodeRun = await planRunService.getNodeRunByNodeId(run.id, nodeSpecRecord.nodeId)
-      if (nodeRun.status === 'monitoring') {
-        // Monitoring nodes are managed by the scheduler — treat as stable
-        return this.serializeRun(run.id)
-      }
-      if (nodeRun.status !== 'running') {
-        return this.serializeRun(run.id)
-      }
-      if (shouldPlanNodeUseVisibleTurn(spec, nodeSpecRecord)) {
-        return this.serializeRun(run.id)
-      }
-
-      const [artifacts, dispatchContext] = await Promise.all([
-        planRunService.listArtifacts(run.id),
-        this.buildDispatchContext(run, spec, nodeSpecRecord),
-      ])
-      const inputArtifacts = artifacts
-        .filter((artifact) => nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
-        .map((artifact) => toArtifactSubmission(artifact))
-
-      try {
-        const result = await this.dispatchNode({
-          nodeSpec: planNode,
-          resolvedInput: nodeRun.resolvedInput ?? {},
-          inputArtifacts,
-          context: { ...dispatchContext, nodeId: planNode.id },
-          executionMode: spec.executionMode,
-          schemaRegistry: spec.schemaRegistry,
-        })
+function toDispatchDatabaseError(message: string, cause: unknown) {
+  return new DatabaseError({ message, cause })
+}
 
-        await planExecutorService.submitNodeResult({
-          threadId: run.threadId,
-          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
-          nodeId: planNode.id,
-          emittedBy: planNode.owner.ref,
-          result,
-        })
-      } catch (error) {
-        await planExecutorService.blockNodeOnDispatchFailure({
-          threadId: run.threadId,
-          runId: recordIdToString(run.id, TABLES.PLAN_RUN),
-          nodeId: planNode.id,
-          emittedBy: planNode.owner.ref,
-          message: formatDispatchError(error),
-          failureClass: classifyDispatchFailure({ ownerType: planNode.owner.executorType, error }),
-        })
-        return await this.serializeRun(run.id)
-      }
+const matchDraftExecutor = (deps: OwnershipDispatcherDeps, node: { id: string; label: string }) =>
+  Match.type<PlanNodeOwner>().pipe(
+    Match.discriminator('executorType')('agent', (owner): PlanValidationIssueInput[] =>
+      deps.agentConfig.roster.includes(owner.ref)
+        ? []
+        : [
+            {
+              severity: 'blocking',
+              code: 'agent_executor_missing',
+              message: `Node "${node.label}" references unknown agent executor "${owner.ref}".`,
+              nodeId: node.id,
+              detail: { agentId: owner.ref },
+            },
+          ],
+    ),
+    Match.discriminator('executorType')('plugin', (owner): PlanValidationIssueInput[] =>
+      deps.pluginExecutor.validateOwner(owner, node.id),
+    ),
+    Match.discriminator('executorType')('system', (owner): PlanValidationIssueInput[] =>
+      deps.systemExecutor.validateOwner(owner, node.id),
+    ),
+    Match.discriminator('executorType')('skill', (): PlanValidationIssueInput[] => []),
+    Match.discriminator('executorType')('user', (): PlanValidationIssueInput[] => []),
+    Match.exhaustive,
+  )
+
+function validateDraftExecutors(deps: OwnershipDispatcherDeps, draft: PlanDraft): PlanValidationIssueInput[] {
+  return draft.nodes.flatMap((node) => matchDraftExecutor(deps, node)(node.owner))
+}
 
-      iteration += 1
+const shouldAutoDispatchEffect = (deps: OwnershipDispatcherDeps, run: PlanRunRecord) =>
+  Effect.gen(function* () {
+    const workspaceProvider = deps.runtimeAdapters.workspaceProvider
+    if (!workspaceProvider) {
+      return true
     }
 
-    throw new Error(
-      `Ownership dispatch exceeded ${MAX_DISPATCH_ITERATIONS} iterations for run ${recordIdToString(
-        ensureRecordId(params.runId, TABLES.PLAN_RUN),
-        TABLES.PLAN_RUN,
-      )}.`,
+    const workspace = yield* Effect.tryPromise(() =>
+      workspaceProvider.getWorkspace(ensureRecordId(run.organizationId, TABLES.ORGANIZATION)),
     )
-  }
-
-  async dispatchReadyNode(params: {
-    run: PlanRunRecord
-    nodeSpecRecord: PlanNodeSpecRecord
-    nodeRun: PlanNodeRunRecord
-    spec: PlanSpecRecord
-    executionModeOverride?: ExecutionMode
-  }): Promise<PlanNodeResultSubmission> {
-    if (shouldPlanNodeUseVisibleTurn(params.spec, params.nodeSpecRecord)) {
-      throw new Error(
-        `Node "${params.nodeSpecRecord.nodeId}" requires a visible plan turn and cannot be silently dispatched.`,
-      )
-    }
-
-    const planNode = toPlanNodeSpec(params.nodeSpecRecord)
-    const [artifacts, dispatchContext] = await Promise.all([
-      planRunService.listArtifacts(params.run.id),
-      this.buildDispatchContext(params.run, params.spec, params.nodeSpecRecord),
-    ])
-    const inputArtifacts = artifacts
-      .filter((artifact) => params.nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
-      .map((artifact) => toArtifactSubmission(artifact))
-
-    return this.dispatchNode({
-      nodeSpec: planNode,
-      resolvedInput: params.nodeRun.resolvedInput ?? {},
-      inputArtifacts,
-      context: { ...dispatchContext, nodeId: planNode.id },
-      executionMode: params.spec.executionMode,
-      executionModeOverride: params.executionModeOverride,
-      schemaRegistry: params.spec.schemaRegistry,
-    })
-  }
-
-  private async shouldAutoDispatch(run: PlanRunRecord): Promise<boolean> {
-    const workspaceProvider = getRuntimeAdapters().workspaceProvider
-    if (!workspaceProvider) {
+    if (!workspaceProvider.getLifecycleState) {
       return true
     }
 
-    const workspace = await workspaceProvider.getWorkspace(ensureRecordId(run.organizationId, TABLES.ORGANIZATION))
-    const lifecycleState = await workspaceProvider.getLifecycleState?.(workspace)
-    return lifecycleState?.bootstrapActive !== true
-  }
-
-  resolveExecutionVisibility(params: { spec: PlanSpecRecord; nodeSpecRecord: PlanNodeSpecRecord }) {
-    return resolvePlanNodeExecutionVisibility(params.spec, params.nodeSpecRecord)
-  }
+    const lifecycleState = yield* Effect.gen(function* () {
+      const result = workspaceProvider.getLifecycleState?.call(workspaceProvider, workspace)
+      if (isPromiseLike(result)) {
+        return yield* Effect.tryPromise(() => result)
+      }
 
-  private async buildDispatchContext(
-    run: PlanRunRecord,
-    spec: PlanSpecRecord,
-    nodeSpecRecord: PlanNodeSpecRecord,
-  ): Promise<Omit<OwnershipDispatchContext, 'nodeId'>> {
+      return result
+    })
+    return lifecycleState ? lifecycleState.bootstrapActive !== true : true
+  })
+
+const buildDispatchContextEffect = (
+  deps: OwnershipDispatcherDeps,
+  run: PlanRunRecord,
+  spec: PlanSpecRecord,
+  nodeSpecRecord: PlanNodeSpecRecord,
+) =>
+  Effect.gen(function* () {
     const organizationId = recordIdToString(run.organizationId, TABLES.ORGANIZATION)
     const threadId = recordIdToString(run.threadId, TABLES.THREAD)
     const planId = recordIdToString(run.id, TABLES.PLAN_RUN)
-    const [thread, nodeSpecs, nodeRuns] = await Promise.all([
-      databaseService.findOne(TABLES.THREAD, { id: ensureRecordId(run.threadId, TABLES.THREAD) }, ThreadSchema),
-      planRunService.listNodeSpecs(spec.id),
-      planRunService.listNodeRuns(run.id),
+    const [thread, nodeSpecs, nodeRuns] = yield* Effect.all([
+      deps.db
+        .findOne(TABLES.THREAD, { id: ensureRecordId(run.threadId, TABLES.THREAD) }, ThreadSchema)
+        .pipe(Effect.mapError((cause) => toDispatchDatabaseError('Failed to load thread context.', cause))),
+      deps.planRun
+        .listNodeSpecs(spec.id)
+        .pipe(Effect.mapError((cause) => toDispatchDatabaseError('Failed to load plan node specs.', cause))),
+      deps.planRun
+        .listNodeRuns(run.id)
+        .pipe(Effect.mapError((cause) => toDispatchDatabaseError('Failed to load plan node runs.', cause))),
     ])
     const userId = thread?.userId ? recordIdToString(thread.userId, TABLES.USER) : undefined
-    const userName = userId
-      ? await userService
-          .getUser(userId)
-          .then((user) => user.name)
-          .catch(() => undefined)
-      : undefined
+    const userResult = userId ? yield* Effect.exit(deps.user.getUser(userId)) : undefined
+    const userName = userResult?._tag === 'Success' ? userResult.value.name : undefined
     const nodeSpecsById = new Map(nodeSpecs.map((candidate) => [candidate.nodeId, candidate]))
     const upstreamHandoffs: UpstreamHandoff[] = nodeRuns
       .filter(
@@ -324,19 +236,17 @@ class OwnershipDispatcherService {
       ...(userName ? { userName } : {}),
       ...(upstreamHandoffs.length > 0 ? { upstreamHandoffs } : {}),
     }
-  }
+  })
 
-  private async serializeRun(runId: RecordIdInput): Promise<SerializableExecutionPlan> {
-    return planRunService.toSerializablePlan(await planRunService.getRunById(runId), {
-      includeEvents: true,
-      includeArtifacts: true,
-      includeApprovals: true,
-      includeCheckpoints: true,
-      includeValidationIssues: true,
-    })
-  }
+const serializeRunEffect = (deps: OwnershipDispatcherDeps, runId: RecordIdInput) =>
+  Effect.gen(function* () {
+    const run = yield* deps.planRun.getRunById(runId)
+    return yield* serializeRunFull(deps.planRun, run)
+  })
 
-  async dispatchNode(params: {
+const dispatchNodeEffect = (
+  deps: OwnershipDispatcherDeps,
+  params: {
     nodeSpec: PlanNodeSpec
     resolvedInput: Record<string, unknown>
     inputArtifacts: PlanArtifactSubmission[]
@@ -344,83 +254,324 @@ class OwnershipDispatcherService {
     executionMode?: ExecutionMode
     executionModeOverride?: ExecutionMode
     schemaRegistry?: PlanSchemaRegistry
-  }) {
+  },
+) =>
+  Effect.gen(function* () {
     const effectiveExecutionMode = params.executionModeOverride ?? params.executionMode
     if (params.nodeSpec.type === 'monitoring' && params.nodeSpec.monitoringConfig) {
-      await monitoringWindowService.startMonitoringWindow({
+      const monitoringConfig = params.nodeSpec.monitoringConfig
+      yield* deps.monitoringWindow.startMonitoringWindow({
         runId: params.context.planId,
         nodeId: params.nodeSpec.id,
-        config: params.nodeSpec.monitoringConfig,
+        config: monitoringConfig,
         organizationId: params.context.organizationId,
         threadId: params.context.threadId,
       })
       return {
         notes: `Monitoring window started for node "${params.nodeSpec.label}".`,
-        structuredOutput: { status: 'monitoring-started', config: params.nodeSpec.monitoringConfig },
+        structuredOutput: { status: 'monitoring-started', config: monitoringConfig },
         artifacts: [],
       }
     }
 
-    if (params.nodeSpec.owner.executorType === 'agent') {
-      return agentExecutorService.executeNode({
-        nodeSpec: params.nodeSpec,
-        resolvedInput: params.resolvedInput,
-        inputArtifacts: params.inputArtifacts,
-        context: params.context,
-        executionMode: effectiveExecutionMode,
-        schemaRegistry: params.schemaRegistry,
-      })
-    }
-    if (params.nodeSpec.owner.executorType === 'plugin') {
-      return pluginExecutorService.executeNode({
-        nodeSpec: params.nodeSpec,
-        resolvedInput: params.resolvedInput,
-        context: params.context,
-      })
-    }
-    if (params.nodeSpec.owner.executorType === 'system') {
-      return systemExecutorService.executeNode({
-        nodeSpec: params.nodeSpec,
-        resolvedInput: params.resolvedInput,
-        context: params.context,
-      })
-    }
-    if (params.nodeSpec.owner.executorType === 'skill') {
-      const resolved = await skillResolverService.resolve({
-        skillRef: params.nodeSpec.owner.ref,
-        organizationId: params.context.organizationId,
-      })
-      if (!resolved) {
-        throw new Error(`Skill "${params.nodeSpec.owner.ref}" could not be resolved. This is a configuration error.`)
-      }
-
-      if (resolved.executorType === 'agent') {
-        const skillNodeSpec = { ...params.nodeSpec, owner: { executorType: 'agent' as const, ref: resolved.ref } }
-        return agentExecutorService.executeNode({
-          nodeSpec: skillNodeSpec,
+    switch (params.nodeSpec.owner.executorType) {
+      case 'agent':
+        return yield* deps.agentExecutor.executeNode({
+          nodeSpec: params.nodeSpec,
           resolvedInput: params.resolvedInput,
           inputArtifacts: params.inputArtifacts,
           context: params.context,
           executionMode: effectiveExecutionMode,
           schemaRegistry: params.schemaRegistry,
         })
+      case 'plugin':
+        return yield* deps.pluginExecutor.executeNode({
+          nodeSpec: params.nodeSpec,
+          resolvedInput: params.resolvedInput,
+          context: params.context,
+        })
+      case 'system':
+        return yield* deps.systemExecutor.executeNode({
+          nodeSpec: params.nodeSpec,
+          resolvedInput: params.resolvedInput,
+          context: params.context,
+        })
+      case 'skill': {
+        const resolved = yield* deps.skillResolver.resolve({
+          skillRef: params.nodeSpec.owner.ref,
+          organizationId: params.context.organizationId,
+        })
+        if (!resolved) {
+          return yield* new ConfigurationError({
+            message: `Skill "${params.nodeSpec.owner.ref}" could not be resolved. This is a configuration error.`,
+          })
+        }
+
+        if (resolved.executorType === 'agent') {
+          const skillNodeSpec = { ...params.nodeSpec, owner: { executorType: 'agent' as const, ref: resolved.ref } }
+          return yield* deps.agentExecutor.executeNode({
+            nodeSpec: skillNodeSpec,
+            resolvedInput: params.resolvedInput,
+            inputArtifacts: params.inputArtifacts,
+            context: params.context,
+            executionMode: effectiveExecutionMode,
+            schemaRegistry: params.schemaRegistry,
+          })
+        }
+
+        return yield* deps.pluginExecutor.executeNode({
+          nodeSpec: {
+            ...params.nodeSpec,
+            owner: {
+              executorType: 'plugin' as const,
+              ref: resolved.ref,
+              operation: resolved.operation ?? params.nodeSpec.owner.ref,
+            },
+          },
+          resolvedInput: params.resolvedInput,
+          context: params.context,
+        })
+      }
+      case 'user':
+        return yield* new BadRequestError({
+          message: `User-owned node "${params.nodeSpec.id}" cannot be auto-dispatched.`,
+        })
+    }
+  })
+
+const dispatchRunToStableBoundaryEffect = (
+  deps: OwnershipDispatcherDeps,
+  params: { runId: RecordIdInput; emittedBy: string },
+) =>
+  Effect.gen(function* () {
+    const initialRun = yield* deps.planRun.getRunById(params.runId)
+    const autoDispatchEnabled = yield* shouldAutoDispatchEffect(deps, initialRun)
+    if (!autoDispatchEnabled) {
+      return yield* serializeRunEffect(deps, initialRun.id)
+    }
+
+    for (let iteration = 0; iteration < MAX_DISPATCH_ITERATIONS; iteration += 1) {
+      const run = yield* deps.planRun.getRunById(params.runId)
+      if (STABLE_RUN_STATUSES.has(run.status) || run.status !== 'running' || !run.currentNodeId) {
+        return yield* serializeRunEffect(deps, run.id)
       }
-      return pluginExecutorService.executeNode({
-        nodeSpec: {
-          ...params.nodeSpec,
-          owner: {
-            executorType: 'plugin' as const,
-            ref: resolved.ref,
-            operation: resolved.operation ?? params.nodeSpec.owner.ref,
+
+      const spec = yield* deps.planRun.getPlanSpecById(run.planSpecId)
+
+      if (spec.executionMode === 'graph-full') {
+        yield* routeGraphFullEffect(
+          { threadId: recordIdToString(run.threadId, TABLES.THREAD), runId: recordIdToString(run.id, TABLES.PLAN_RUN) },
+          {
+            dispatchReadyNode: (dispatchParams) => dispatchReadyNodeEffect(deps, dispatchParams),
+            planExecutorService: deps.planExecutor,
+            planRunService: deps.planRun,
           },
-        },
-        resolvedInput: params.resolvedInput,
-        context: params.context,
+        ).pipe(
+          Effect.catch(() =>
+            Effect.fail(
+              new ConfigurationError({
+                message: `Failed to route graph-full execution for run ${recordIdToString(run.id, TABLES.PLAN_RUN)}.`,
+              }),
+            ),
+          ),
+        )
+        return yield* serializeRunEffect(deps, run.id)
+      }
+
+      const currentNodeId = run.currentNodeId
+      if (!currentNodeId) {
+        return yield* serializeRunEffect(deps, run.id)
+      }
+
+      const nodeSpecRecord = yield* deps.planRun.getNodeSpecByNodeId(spec.id, currentNodeId)
+      const planNode = toPlanNodeSpec(nodeSpecRecord)
+      if (planNode.owner.executorType === 'user') {
+        return yield* serializeRunEffect(deps, run.id)
+      }
+
+      const nodeId = nodeSpecRecord.nodeId
+      if (!nodeId) {
+        return yield* new ConfigurationError({
+          message: `Node spec "${nodeSpecRecord.label}" is missing an executable node id.`,
+        })
+      }
+
+      const nodeRun = yield* deps.planRun.getNodeRunByNodeId(run.id, nodeId)
+      if (nodeRun.status === 'monitoring') {
+        return yield* serializeRunEffect(deps, run.id)
+      }
+      if (nodeRun.status !== 'running') {
+        return yield* serializeRunEffect(deps, run.id)
+      }
+      if (shouldPlanNodeUseVisibleTurn(spec, nodeSpecRecord)) {
+        return yield* serializeRunEffect(deps, run.id)
+      }
+
+      const [artifacts, dispatchContext] = yield* Effect.all([
+        deps.planRun
+          .listArtifacts(run.id)
+          .pipe(Effect.mapError((cause) => toDispatchDatabaseError('Failed to load run artifacts.', cause))),
+        buildDispatchContextEffect(deps, run, spec, nodeSpecRecord),
+      ])
+      const inputArtifacts = artifacts
+        .filter((artifact) => nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
+        .map((artifact) => toArtifactSubmission(artifact))
+
+      const dispatchExit = yield* Effect.exit(
+        Effect.gen(function* () {
+          const result = yield* dispatchNodeEffect(deps, {
+            nodeSpec: planNode,
+            resolvedInput: nodeRun.resolvedInput ?? {},
+            inputArtifacts,
+            context: { ...dispatchContext, nodeId: planNode.id },
+            executionMode: spec.executionMode,
+            schemaRegistry: spec.schemaRegistry,
+          })
+
+          yield* Effect.tryPromise(() =>
+            deps.planExecutor.submitNodeResult({
+              threadId: run.threadId,
+              runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+              nodeId: planNode.id,
+              emittedBy: planNode.owner.ref,
+              result,
+            }),
+          )
+        }),
+      )
+
+      if (dispatchExit._tag === 'Failure') {
+        const failure = Cause.squash(dispatchExit.cause)
+        yield* Effect.tryPromise(() =>
+          deps.planExecutor.blockNodeOnDispatchFailure({
+            threadId: run.threadId,
+            runId: recordIdToString(run.id, TABLES.PLAN_RUN),
+            nodeId: planNode.id,
+            emittedBy: planNode.owner.ref,
+            message: formatDispatchError(failure),
+            failureClass: classifyDispatchFailure({ ownerType: planNode.owner.executorType, error: failure }),
+          }),
+        )
+        return yield* serializeRunEffect(deps, run.id)
+      }
+    }
+
+    return yield* new ConfigurationError({
+      message: `Ownership dispatch exceeded ${MAX_DISPATCH_ITERATIONS} iterations for run ${recordIdToString(
+        ensureRecordId(params.runId, TABLES.PLAN_RUN),
+        TABLES.PLAN_RUN,
+      )}.`,
+    })
+  })
+
+const dispatchReadyNodeEffect = (
+  deps: OwnershipDispatcherDeps,
+  params: {
+    run: PlanRunRecord
+    nodeSpecRecord: PlanNodeSpecRecord
+    nodeRun: PlanNodeRunRecord
+    spec: PlanSpecRecord
+    executionModeOverride?: ExecutionMode
+  },
+) =>
+  Effect.gen(function* () {
+    if (shouldPlanNodeUseVisibleTurn(params.spec, params.nodeSpecRecord)) {
+      return yield* new BadRequestError({
+        message: `Node "${params.nodeSpecRecord.nodeId}" requires a visible plan turn and cannot be silently dispatched.`,
       })
     }
 
-    throw new Error(`User-owned node "${params.nodeSpec.id}" cannot be auto-dispatched.`)
-  }
+    const planNode = toPlanNodeSpec(params.nodeSpecRecord)
+    const [artifacts, dispatchContext] = yield* Effect.all([
+      deps.planRun
+        .listArtifacts(params.run.id)
+        .pipe(Effect.mapError((cause) => toDispatchDatabaseError('Failed to load run artifacts.', cause))),
+      buildDispatchContextEffect(deps, params.run, params.spec, params.nodeSpecRecord),
+    ])
+    const inputArtifacts = artifacts
+      .filter((artifact) => params.nodeSpecRecord.upstreamNodeIds.includes(artifact.nodeId))
+      .map((artifact) => toArtifactSubmission(artifact))
+
+    return yield* dispatchNodeEffect(deps, {
+      nodeSpec: planNode,
+      resolvedInput: params.nodeRun.resolvedInput ?? {},
+      inputArtifacts,
+      context: { ...dispatchContext, nodeId: planNode.id },
+      executionMode: params.spec.executionMode,
+      executionModeOverride: params.executionModeOverride,
+      schemaRegistry: params.spec.schemaRegistry,
+    })
+  })
+
+function resolveExecutionVisibility(params: { spec: PlanSpecRecord; nodeSpecRecord: PlanNodeSpecRecord }) {
+  return resolvePlanNodeExecutionVisibility(params.spec, params.nodeSpecRecord)
 }
 
-export const ownershipDispatcherService = new OwnershipDispatcherService()
+export function makeOwnershipDispatcherService(deps: OwnershipDispatcherDeps) {
+  return {
+    validateDraftExecutors(draft: PlanDraft) {
+      return validateDraftExecutors(deps, draft)
+    },
+    dispatchRunToStableBoundary(params: { runId: RecordIdInput; emittedBy: string }) {
+      return dispatchRunToStableBoundaryEffect(deps, params)
+    },
+    dispatchReadyNode(params: {
+      run: PlanRunRecord
+      nodeSpecRecord: PlanNodeSpecRecord
+      nodeRun: PlanNodeRunRecord
+      spec: PlanSpecRecord
+      executionModeOverride?: ExecutionMode
+    }) {
+      return dispatchReadyNodeEffect(deps, params)
+    },
+    resolveExecutionVisibility(params: { spec: PlanSpecRecord; nodeSpecRecord: PlanNodeSpecRecord }) {
+      return resolveExecutionVisibility(params)
+    },
+    dispatchNode(params: {
+      nodeSpec: PlanNodeSpec
+      resolvedInput: Record<string, unknown>
+      inputArtifacts: PlanArtifactSubmission[]
+      context: OwnershipDispatchContext
+      executionMode?: ExecutionMode
+      executionModeOverride?: ExecutionMode
+      schemaRegistry?: PlanSchemaRegistry
+    }) {
+      return dispatchNodeEffect(deps, params)
+    },
+  } as const
+}
+
+export class OwnershipDispatcherServiceTag extends Context.Service<
+  OwnershipDispatcherServiceTag,
+  ReturnType<typeof makeOwnershipDispatcherService>
+>()('OwnershipDispatcherService') {}
+
+export const OwnershipDispatcherServiceLive = Layer.effect(
+  OwnershipDispatcherServiceTag,
+  Effect.gen(function* () {
+    const db = yield* DatabaseServiceTag
+    const agentConfig = yield* AgentConfigServiceTag
+    const runtimeAdapters = yield* RuntimeAdaptersServiceTag
+    const planRun = yield* PlanRunServiceTag
+    const agentExecutor = yield* AgentExecutorServiceTag
+    const monitoringWindow = yield* MonitoringWindowServiceTag
+    const planExecutor = yield* PlanExecutorServiceTag
+    const pluginExecutor = yield* PluginExecutorServiceTag
+    const skillResolver = yield* SkillResolverServiceTag
+    const systemExecutor = yield* SystemExecutorServiceTag
+    const user = yield* UserServiceTag
+    return makeOwnershipDispatcherService({
+      db,
+      agentConfig,
+      runtimeAdapters,
+      agentExecutor,
+      monitoringWindow,
+      planExecutor,
+      planRun,
+      pluginExecutor,
+      skillResolver,
+      systemExecutor,
+      user,
+    })
+  }),
+)